Dynamic Access Control for OAuth

[ryceg]

As an admin of a Nocturne instance,
I want API endpoints to query and toggle access for any registered OAuth client or person,
so that I can automate who has access to my child's data based on real-world caregiving context.

---

Querying Access State

Query a specific subject's access

As an admin,
I want to query the current access state of a specific person or OAuth client,
so that external automations can make decisions based on who currently has access.

Acceptance Criteria:

• GET /api/v4/access/{subjectId} returns the current enabled/disabled state, the subject type (person or client), and when access was last toggled.
• The endpoint accepts either a person ID or an OAuth client ID.
• Response includes metadata like display name and granted scopes so automations can confirm they're targeting the right subject.

List all subjects and their access states

As an admin,
I want to list all people and OAuth clients with their current access states,
so that I can build dashboards or audit who has access at any given time.

Acceptance Criteria:

• GET /api/v4/access returns all subjects with their access states.
• Supports filtering by state (enabled/disabled), subject type, and scope.
• Pagination is supported for instances with many registered clients.

---

Toggling Access

Enable or disable access via API

As an admin,
I want to enable or disable access for a specific person or OAuth client via API,
so that I can grant or revoke data access programmatically without logging into a UI.

Acceptance Criteria:

• PUT /api/v4/access/{subjectId} accepts a body with { "enabled": true | false }.
• Toggling access takes effect immediately — active sessions/tokens for disabled subjects are invalidated or rejected on next use.
• The response confirms the new state and timestamp.
• An audit log entry is created recording who toggled access, for whom, and when.

Temporary access grants with auto-expiry

As an admin,
I want to set a temporary access grant with an automatic expiry,
so that I don't have to remember to revoke access manually after a custody period or school day ends.

Acceptance Criteria:

• The toggle endpoint accepts an optional expiresAt (ISO 8601 datetime) or duration (e.g. PT8H).
• Access is automatically revoked when the expiry is reached.
• The query endpoint includes expiry information when a temporary grant is active.
• An event/webhook fires when access auto-expires, so automations can react if needed.

---

Automation Integration Scenarios

Tasker: Custody schedule automation

As a co-parent using Tasker,
I want to call the access toggle endpoint on a schedule matching my custody arrangement,
so that my ex-partner automatically gets access to our child's CGM data during their custody days without any manual steps from me.

Acceptance Criteria:

• The API authenticates via a long-lived admin API key or OAuth token suitable for background automation.
• The endpoint is idempotent — calling enable when already enabled is a no-op, not an error.

IFTTT: School calendar integration

As a parent using IFTTT,
I want to trigger access changes based on my child's school calendar,
so that school staff have access to CGM data during school hours and term time only.

Acceptance Criteria:

• The API supports simple webhook-style calls compatible with IFTTT's HTTP action (single URL, JSON body, bearer token auth).
• Convenience endpoints POST /api/v4/access/{subjectId}/enable and POST /api/v4/access/{subjectId}/disable are available for platforms that struggle with varying request bodies.

Apple Shortcuts: Conditional daycare access

As a parent using Apple Shortcuts,
I want to query today's calendar for "Daycare" events and conditionally enable the daycare's access,
so that caregivers only see data on days my child actually attends.

Acceptance Criteria:

• The query endpoint responds quickly enough for use in a Shortcuts workflow (the calendar check happens client-side in Shortcuts; Nocturne just needs to handle the toggle).
• Auth works with a static bearer token that can be stored in Shortcuts without re-authentication flows.

---

Safety & Guardrails

Prevent admin self-lockout

As an admin,
I want toggling access to never affect my own admin access,
so that a misconfigured automation can't lock me out of my own instance.

Acceptance Criteria:

• The API rejects attempts to disable the last remaining admin.
• Self-disabling requires explicit confirmation (a separate flag in the request body).

Access change audit history

As an admin,
I want to see a history of all access changes,
so that I can verify my automations are working correctly and troubleshoot if a caregiver reports they couldn't access data.

Acceptance Criteria:

• GET /api/v4/access/{subjectId}/history returns a chronological log of state changes with timestamps, source (manual/API/auto-expiry), and the acting principal.
• History is retained for a configurable period (default 90 days).