@oxyhq/contracts 0.25.0 → 0.26.0

package/dist/esm/browserHub.js

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+import { deviceDirectorySchema } from './deviceDirectory.js';
+/**
+ * The browser DeviceSession hub at `auth.oxy.so` (issue #937, Phase 5, ADR 0003).
+ *
+ * Two wire surfaces live in this file and they are deliberately different
+ * shapes, because they answer to different callers:
+ *
+ *  - The `browserHub*` schemas below the first divider are the API's
+ *    (`api.oxy.so/session/browser-hub/*`), spoken ONLY by the IdP's own
+ *    server/edge layer. They carry the raw handle and a bearer, so nothing that
+ *    speaks them may run in a browser.
+ *  - The `hub*` schemas below the second divider are the EDGE's
+ *    (`auth.oxy.so/hub/*`), spoken by the IdP SPA. They carry neither: the
+ *    handle stays in an `HttpOnly` cookie the script cannot read, and the
+ *    device-wide bearer stays at the edge.
+ *
+ * That split is the whole point of the phase. A single schema covering both
+ * would let a refactor move a credential across the boundary without any type
+ * changing shape.
+ *
+ * ## What is NOT reopened here
+ *
+ * Relying-party origins remain zero-cookie: they keep `{deviceId,
+ * deviceSecret}` + `POST /session/device/token` and set no cookie of any kind.
+ * `auth.oxy.so` alone holds a handle, first-party only. There is no
+ * refresh-token family and no bootstrap hop.
+ */
+/* -------------------------------------------------------------------------- */
+/*  The cookie                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * The one cookie name, `__Host-` prefixed.
+ *
+ * The prefix is not decoration: a browser refuses to store a `__Host-` cookie
+ * that carries a `Domain` attribute or a `Path` other than `/`, or that arrives
+ * without `Secure`. So the name itself is what makes "bound to `auth.oxy.so`
+ * alone, readable by no other `oxy.so` host" enforced by the client rather than
+ * merely intended by the server — including against a compromised sibling
+ * subdomain, which is the specific attack `Domain=.oxy.so` would have opened.
+ */
+export const BROWSER_HUB_COOKIE_NAME = '__Host-oxy-device';
+/**
+ * The exact attribute set the edge sets, in the order it writes them.
+ *
+ * Held as data rather than as a template string so a test can assert the set
+ * rather than a rendered line, and so removing one attribute is a diff to a
+ * named constant instead of an edit inside a string literal.
+ *
+ * `Max-Age` is deliberately NOT in this list — see
+ * {@link BROWSER_HUB_HANDLE_TTL_MS}, which the edge appends. Everything here is
+ * a SECURITY attribute and none of them is ever conditional.
+ */
+export const BROWSER_HUB_COOKIE_ATTRIBUTES = ['Secure', 'HttpOnly', 'SameSite=Lax', 'Path=/'];
+/**
+ * How long a hub handle lives, server-side and in the cookie alike.
+ *
+ * Thirty days. The cookie's `Max-Age` is derived from this same constant so the
+ * two cannot disagree: a cookie outliving its credential produces a browser that
+ * believes it is signed in and is refused on every call, and a credential
+ * outliving its cookie leaves an un-addressable row alive on the server.
+ *
+ * A hub handle is NOT a session cookie (one with no `Max-Age`, discarded when
+ * the browser closes). It cannot be: the thing it identifies is the browser
+ * PROFILE's device session, and a device session that evaporates when the user
+ * quits their browser would send them back to a QR scan every morning — the
+ * exact failure ADR 0003 exists to remove.
+ */
+export const BROWSER_HUB_HANDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/* -------------------------------------------------------------------------- */
+/*  api.oxy.so/session/browser-hub/*  —  spoken by the edge, never a browser   */
+/* -------------------------------------------------------------------------- */
+/**
+ * The raw handle, as it travels between the edge and the API.
+ *
+ * An opaque base64url random value and NOTHING else — no token, no user id, no
+ * device id, no account id, no serialized state. The server stores only
+ * `sha256(handle)`, so a dump of the column cannot address a browser.
+ *
+ * The minimum length is a floor against an empty or truncated value reaching a
+ * hash comparison, not a statement about the entropy: that is fixed by the
+ * issuer (`BROWSER_HUB_HANDLE_BYTES` in the API), and a handle is the only
+ * credential in this flow, so it is 256 bits.
+ */
+export const browserHubHandleSchema = z.string().min(32);
+/** Request body of every handle-presenting API endpoint. */
+export const browserHubHandleRequestSchema = z.object({
+    handle: browserHubHandleSchema,
+});
+/**
+ * Response of `POST /session/browser-hub/establish` and `.../rotate`.
+ *
+ * The raw handle is returned exactly ONCE, to the edge, which puts it straight
+ * into the cookie and keeps no copy. It is never logged, never re-readable, and
+ * never reaches the browser's script context.
+ */
+export const browserHubHandleResponseSchema = z.object({
+    handle: browserHubHandleSchema,
+    expiresAt: z.string(),
+});
+/**
+ * Response of `POST /session/browser-hub/resolve` — the browser's device
+ * session, resolved from the handle alone.
+ *
+ * Carries a bearer because the edge needs one to run the authorize lane on the
+ * browser's behalf. It is the ordinary short-lived access token of the device's
+ * active context, and it stops at the edge.
+ */
+export const browserHubResolveResponseSchema = z.object({
+    accessToken: z.string().min(1),
+    expiresAt: z.string(),
+    directory: deviceDirectorySchema,
+});
+/**
+ * Why a handle did not resolve. A CLOSED set, and deliberately coarse.
+ *
+ *  - `invalid_handle`    — unknown, expired, or revoked. One code for all
+ *                          three: distinguishing them would tell a caller
+ *                          holding a guessed value whether it ever existed.
+ *  - `no_active_session` — the handle is good and the device has nothing live
+ *                          to mint for. The credential is NOT revoked; the
+ *                          browser re-authenticates and keeps its cookie.
+ */
+export const browserHubErrorSchema = z.enum(['invalid_handle', 'no_active_session']);
+/** Response of `POST /session/browser-hub/revoke`. Idempotent by construction. */
+export const browserHubRevokeResponseSchema = z.object({
+    revoked: z.boolean(),
+});
+/* -------------------------------------------------------------------------- */
+/*  auth.oxy.so/hub/*  —  spoken by the IdP SPA                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * What the SPA is allowed to know about the hub session.
+ *
+ * `signed_out` covers "no cookie", "cookie present but the handle no longer
+ * resolves" and "resolved, but the device has nothing live" — from the script's
+ * side those are one state, and collapsing them here is what stops a UI from
+ * branching on a distinction it must not act on.
+ *
+ * `active` carries the DIRECTORY and no credential. A switcher renders from it;
+ * nothing in it can be spent against the API. The bearer that produced it never
+ * left the edge.
+ */
+export const hubSessionSchema = z.discriminatedUnion('status', [
+    z.object({ status: z.literal('signed_out') }),
+    z.object({ status: z.literal('active'), directory: deviceDirectorySchema }),
+]);
+/** Request body of `POST /hub/claim` — the Commons approval lane's handoff. */
+export const hubClaimRequestSchema = z.object({
+    /**
+     * The secret `sessionToken` of an approved `AuthSession`, held only by the
+     * page that created it. The edge spends it server-side: the access token and
+     * device secret the claim yields are consumed to establish the hub and are
+     * then discarded, so neither is ever returned to the script.
+     */
+    sessionToken: z.string().min(1),
+});
+/** Request body of `POST /hub/activate` — pick the globally active context. */
+export const hubActivateRequestSchema = z.object({
+    contextId: z.string().min(1),
+});
+/**
+ * Request body of `POST /hub/authorize` — a later official origin joining.
+ *
+ * There is no `prompt` field, and that is not an omission. `'none'` is absent
+ * from `buildOAuthAuthorizeUrl`'s union in `@oxyhq/core` precisely so a silent
+ * loop cannot be rebuilt in one line, and this endpoint would be the second
+ * place to rebuild it. A caller that needs a login or consent prompt gets one
+ * by not passing `approve`.
+ */
+export const hubAuthorizeRequestSchema = z.object({
+    clientId: z.string().min(1),
+    redirectUri: z.string().url(),
+    state: z.string().optional(),
+    codeChallenge: z.string().min(1),
+    /** S256 only. `plain` is refused before the request leaves the edge. */
+    codeChallengeMethod: z.literal('S256'),
+    scope: z.string().optional(),
+    /**
+     * The user's explicit answer on the consent screen.
+     *
+     * Absent or `false` means "tell me whether consent is needed"; the edge then
+     * returns `consent_required` and mints nothing. Only `true` may mint, and only
+     * the consent screen's own button sends it — which is why the decision of
+     * WHETHER consent is required is re-read from the server on both passes rather
+     * than remembered from the first.
+     */
+    approve: z.boolean().optional(),
+});
+/**
+ * Result of `POST /hub/authorize`.
+ *
+ * `signed_out` is the honest answer for a browser with no hub session: the SPA
+ * runs the ordinary Commons-first authentication and tries again. It is never a
+ * redirect the edge performs on the browser's behalf — no automatic chain
+ * across Oxy origins, and nothing here can be hidden inside an iframe.
+ */
+export const hubAuthorizeResultSchema = z.discriminatedUnion('status', [
+    z.object({ status: z.literal('signed_out') }),
+    z.object({
+        status: z.literal('consent_required'),
+        reason: z.enum(['new', 'scope_changed']),
+        userConsentScopes: z.array(z.string()).optional(),
+    }),
+    z.object({
+        status: z.literal('code'),
+        code: z.string().min(1),
+        state: z.string().nullable(),
+        redirectUri: z.string(),
+        expiresIn: z.number().int().positive(),
+    }),
+]);

package/dist/esm/deviceDirectory.js

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+import { accountKindSchema } from './accountGraph.js';
+import { activeTokenSchema, deviceSessionStateSchema } from './deviceSession.js';
+import { userNameSchema } from './userResponse.js';
+/**
+ * The canonical device directory — the ONE server-authoritative read model an
+ * account switcher renders (issue #937, ADR 0002).
+ *
+ * It replaces the client-side union of `DeviceSessionState.accounts[]` with a
+ * separately fetched `AccountNode[]` graph. That union cannot be correct on a
+ * device holding more than one person: the client only ever holds ONE caller's
+ * account graph, so it cannot enumerate what the OTHER principals may act as.
+ * Switchability is an authorization question, so the server answers it.
+ *
+ * The directory is deterministic and revision-bound: two reads at the same
+ * `revision` describe the same device state, and `revision` only advances on a
+ * real mutation (an idempotent activation advances nothing — ADR 0002).
+ */
+/**
+ * How a principal reaches an account.
+ *
+ * Mirrors `AccountRelationship` in `@oxyhq/core`'s account graph rather than
+ * inventing a second vocabulary for the same fact:
+ *  - `self`   — the principal's own personal account (`principal.userId === accountId`)
+ *  - `owner`  — the principal owns this account
+ *  - `member` — the principal holds a membership granting `account:act_as`
+ */
+export const deviceContextRelationshipSchema = z.enum(['self', 'owner', 'member']);
+/**
+ * Sanitized display metadata for a principal or an account context.
+ *
+ * Deliberately NOT `userResponseSchema`: a switcher needs a handle, a name, an
+ * avatar and the accent the row is drawn in, and the directory is read by every
+ * app on the device — so it carries the minimum that renders a row and nothing
+ * that would make it a general profile feed. `name.displayName` stays OPTIONAL;
+ * consumers fall back to the handle (`getNormalizedUserHandle`), never to a
+ * synthesized name.
+ *
+ * `color` is here and `email` is not, and the line between them is what the
+ * field is FOR rather than how sensitive it looks. An accent is a property of
+ * drawing the row — without it every non-active row falls back to the ambient
+ * theme accent and a device holding two people renders them identically
+ * (issue #961). An address is somebody's contact detail, and the `@handle` the
+ * secondary line already shows fills the same slot, so putting one in a payload
+ * every installed app reads would widen the profile for no rendering gain.
+ */
+export const deviceDirectoryProfileSchema = z.object({
+    id: z.string().min(1),
+    username: z.string(),
+    name: userNameSchema.optional(),
+    avatar: z.string().nullable().optional(),
+    /**
+     * Named Bloom color preset (e.g. `"blue"`), or null when the account has
+     * none. Same shape as `userResponseSchema.color` — one spelling of one fact,
+     * so a consumer that themes a row from either source reads the same values.
+     */
+    color: z.string().nullable().optional(),
+});
+/**
+ * One `principal acting as account` pair — the globally switchable unit.
+ *
+ * `id` is the identifier `POST /session/device/activate` takes. It names the
+ * PAIR, not the account: the same `accountId` legitimately appears under two
+ * principals on a shared device, and those are different sessions, permissions,
+ * audit actors and revocation paths.
+ *
+ * `onDevice` is `false` for a context the principal may act as but has never
+ * activated here — it exists as a row so it has a stable id to activate, and
+ * its delegated session is minted on first activation rather than eagerly for
+ * every organization the principal belongs to.
+ *
+ * `available` is `principalLive && (personal || live account:act_as)`, and the
+ * principal clause is not decoration: a principal whose own personal session
+ * has died makes EVERY context of theirs unavailable, including delegated ones
+ * whose sessions are perfectly alive. Activation verifies the principal's
+ * personal session (ADR 0002 step 3), so a client that models availability as
+ * "delegated context has a live session ⇒ activatable" will be refused by the
+ * server and the context healed away.
+ *
+ * A managed account whose membership was revoked is returned with
+ * `available: false` rather than silently omitted, so the UI can explain a row
+ * disappearing instead of just dropping it.
+ *
+ * (An earlier version of this comment described `available` as the
+ * `account:act_as` verdict alone. It was written before the server existed and
+ * was weaker than the code that shipped — the kind of wrong statement nothing
+ * recomputes, so it is spelled out here in full.)
+ */
+export const deviceAccountContextSchema = z.object({
+    id: z.string().min(1),
+    accountId: z.string().min(1),
+    kind: accountKindSchema,
+    relationship: deviceContextRelationshipSchema,
+    account: deviceDirectoryProfileSchema,
+    onDevice: z.boolean(),
+    available: z.boolean(),
+    active: z.boolean(),
+    lastUsedAt: z.number().nullable(),
+});
+/**
+ * A human who authenticated onto this device.
+ *
+ * Never an organization, project, channel or bot — those are subjects a
+ * principal acts as, and they appear only in `contexts`. `authuser` is the
+ * Google-style signed-in-human slot and belongs HERE, not to an account: adding
+ * an organization must never consume one.
+ */
+export const devicePrincipalSchema = z.object({
+    id: z.string().min(1),
+    userId: z.string().min(1),
+    authuser: z.number().int().nonnegative(),
+    user: deviceDirectoryProfileSchema,
+    contexts: z.array(deviceAccountContextSchema),
+});
+/**
+ * Response of `GET /session/device/directory`.
+ *
+ * `activeContextId` is the authority for what every official app in
+ * `sessionMode: 'account'` renders. It is null when the device has no active
+ * context — a real state (every context removed, or an active context healed
+ * away), not an error.
+ */
+export const deviceDirectorySchema = z.object({
+    deviceId: z.string().min(1),
+    revision: z.number().int().nonnegative(),
+    activeContextId: z.string().nullable(),
+    principals: z.array(devicePrincipalSchema),
+    updatedAt: z.number(),
+});
+/**
+ * Request body of `POST /session/device/activate`.
+ *
+ * `contextId`, never `accountId`: an account id cannot name a context on a
+ * device where two people can both reach the same organization, and resolving
+ * that ambiguity server-side would mean guessing inside an authorization path.
+ */
+export const deviceActivateRequestSchema = z.object({
+    contextId: z.string().min(1),
+});
+/**
+ * Response of `POST /session/device/activate`.
+ *
+ * Carries the post-transition directory AND the bearer for the newly active
+ * context, because the client's ordering invariant is
+ * `commit token → reset caches → publish snapshot → notify` (ADR 0002). Handing
+ * the directory back without the token would force a second round trip in the
+ * middle of that sequence, which is exactly where a component would render the
+ * new subject while still holding the previous subject's bearer.
+ *
+ * `activeToken` is null when the activation legitimately produced no bearer for
+ * THIS caller — an identity-pinned client, or a caller whose application is not
+ * entitled to a token for the new context. It is never an error signal.
+ */
+export const deviceActivateResponseSchema = z.object({
+    directory: deviceDirectorySchema,
+    activeToken: activeTokenSchema.nullable(),
+});
+/**
+ * Response of the CONTEXT-aware removals — `POST /session/device/signout` with
+ * `{ contextId }` (one `principal → account` pair) or `{ principalId }` (one
+ * person and every context they reach, and nobody else's).
+ *
+ * It carries BOTH halves because a removal elects a replacement active context,
+ * so both the directory and the flat compatibility projection move in the same
+ * transition — and a client that learned only one of them would render one
+ * half of a device that no longer exists.
+ *
+ * This is deliberately NOT {@link deviceSessionSyncSchema} and must never be
+ * merged into it. A zod object strips unknown keys, so `{directory, state,
+ * activeToken}` parses cleanly as `{state, activeToken}` — silently dropping the
+ * directory. One schema covering both shapes would therefore make "the server
+ * stopped sending the directory" and "this endpoint never sends one"
+ * indistinguishable at the parse, on the exact path that decides which identity
+ * the app is running as. Two schemas fail closed instead: `directory` is
+ * required here, so a directory-less payload is refused outright.
+ *
+ * `activeToken` is null on the same terms as everywhere else — an identity-
+ * pinned caller, or one not entitled to a bearer for the newly-elected context —
+ * and null is also the honest answer when the removal left the device with no
+ * active context at all.
+ */
+export const deviceDirectorySyncSchema = z.object({
+    directory: deviceDirectorySchema,
+    state: deviceSessionStateSchema,
+    activeToken: activeTokenSchema.nullable(),
+});

package/dist/esm/index.js

@@ -70,6 +70,9 @@ export {
 // Schemas
 linkPreviewSchema, linkPreviewBatchRequestSchema, linkPreviewBatchResponseSchema, linkPreviewResponseSchema, } from './links.js';
 export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceBackgroundCredentialResponseSchema, deviceBackgroundTokenRequestSchema, deviceBackgroundTokenResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession.js';
+export { deviceContextRelationshipSchema, deviceDirectoryProfileSchema, deviceAccountContextSchema, devicePrincipalSchema, deviceDirectorySchema, deviceActivateRequestSchema, deviceActivateResponseSchema, deviceDirectorySyncSchema, } from './deviceDirectory.js';
+export { oauthConsentDecisionSchema, oauthAuthorizeCodeResponseSchema, } from './oauth.js';
+export { BROWSER_HUB_COOKIE_NAME, BROWSER_HUB_COOKIE_ATTRIBUTES, BROWSER_HUB_HANDLE_TTL_MS, browserHubHandleSchema, browserHubHandleRequestSchema, browserHubHandleResponseSchema, browserHubResolveResponseSchema, browserHubErrorSchema, browserHubRevokeResponseSchema, hubSessionSchema, hubClaimRequestSchema, hubActivateRequestSchema, hubAuthorizeRequestSchema, hubAuthorizeResultSchema, } from './browserHub.js';
 export { 
 // Schemas
 loginResultSchema, } from './deviceBoot.js';

package/dist/esm/oauth.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+/**
+ * The two `/auth/oauth/*` responses the browser hub's edge layer reads.
+ *
+ * They existed on the wire long before this file — `GET /auth/oauth/consent`
+ * and `POST /auth/oauth/authorize` are the surface `auth.oxy.so` has always
+ * driven with a bearer. What is new (issue #937 Phase 5) is a SECOND consumer
+ * that is not the SPA: the IdP's edge layer runs both calls server-side so the
+ * device-wide bearer never enters the browser's script context. A shape read by
+ * two independently deployed consumers is a contract, so it is written down
+ * once here and validated on both sides rather than transcribed into the edge.
+ *
+ * These are NOT the RFC 6749 token/userinfo responses. Those two speak flat
+ * OAuth/OIDC on the wire and are the one place in the API that does not use the
+ * `{ data }` envelope; these two are ordinary internal API responses that happen
+ * to be about OAuth.
+ */
+/**
+ * Server-authoritative answer to "must this user be shown a consent screen".
+ *
+ * Discriminated on `consentRequired` so the two arms cannot be confused by a
+ * consumer that reads `reason` first: `trusted`/`granted` are reasons NOT to
+ * ask, `new`/`scope_changed` are reasons to ask, and a flat object would let a
+ * typo in one produce a plausible value of the other.
+ *
+ *  - `trusted`       — the application is first-party/internal/system/official
+ *                      by the REGISTRY's verdict (`isTrustedApplication`), and
+ *                      the request names no scope over the user's own follow
+ *                      graph. Never inferred from a hostname.
+ *  - `granted`       — a prior `AppGrant` already covers every requested scope.
+ *  - `scope_changed` — a prior grant exists and is missing one.
+ *  - `new`           — no prior grant.
+ *
+ * `userConsentScopes` names the scopes that FORCED the screen, so the consent UI
+ * can say which one it is asking about. Present only on the `true` arm, and only
+ * when such a scope exists — a trusted app asked for one is still asked.
+ */
+export const oauthConsentDecisionSchema = z.discriminatedUnion('consentRequired', [
+    z.object({
+        consentRequired: z.literal(false),
+        reason: z.enum(['trusted', 'granted']),
+    }),
+    z.object({
+        consentRequired: z.literal(true),
+        reason: z.enum(['new', 'scope_changed']),
+        userConsentScopes: z.array(z.string()).optional(),
+    }),
+]);
+/**
+ * A minted authorization code.
+ *
+ * `state` is echoed back as the caller sent it and is `null` when they sent
+ * none — never omitted, so a consumer cannot read "the server dropped my state"
+ * as "I sent none". `redirectUri` is echoed for the same reason the code is
+ * bound to it server-side: the caller must be able to see that the value the
+ * code was issued against is the one it registered.
+ */
+export const oauthAuthorizeCodeResponseSchema = z.object({
+    code: z.string().min(1),
+    state: z.string().nullable(),
+    redirectUri: z.string(),
+    expiresIn: z.number().int().positive(),
+});