@oaath/server 0.1.0 → 0.3.1

package/README.md

@@ -17,11 +17,116 @@ import { createPostgresRelayStore } from "@oaath/server/postgres";
 const handler = createRelayHandler({
   store: createPostgresRelayStore({ connectionString }),
   authentication, // deployment-owned client/device authentication
+  ownerRouting, // resolveOwner(caller, request) returns { ownerDeviceId, ownerSubject } or null
   kms, // deployment-owned encrypt/decrypt; plaintext never reaches the store
   clock: { now: () => Date.now() },
 });
 ```
 
+`ownerRouting.resolveOwner(caller, { requestId, requestedScope })` is required.
+The relay captures its route once in the immutable request; null refuses creation.
+The approving phone authenticates as `ownerSubject`, independently of the requesting
+member. Changing the resolver cannot redirect an existing request. Requester
+authentication and grant reference verification retain the member's subject.
+
+## Service directory
+
+`createServiceDirectory(store)` owns the records used to select a personal or
+team account. Pass the directory as both `bootstrap` and `ownerRouting`:
+
+```ts
+import { createServiceDirectory } from "@oaath/server";
+import {
+  createPostgresServiceDirectorySchema,
+  createPostgresServiceDirectoryStore,
+} from "@oaath/server/postgres";
+
+// Provision once in a new schema. Existing schemas are not migrated.
+await createPostgresServiceDirectorySchema(pool);
+const directory = createServiceDirectory(
+  createPostgresServiceDirectoryStore({ pool }),
+);
+await directory.replace({ expectedRevision: null, directory: initialDirectory });
+const handler = createRelayHandler({ store, authentication, kms, clock, chains,
+  bootstrap: directory, ownerRouting: directory });
+```
+
+The `oaath.service-directory/v1` document contains `workspaces`, `applications`,
+`memberships`, `accounts`, `ownerDevices`, and `selections`. Membership uses
+the authenticated `(clientId, subject)` pair; an account references an owner
+device within its workspace. Each account owns its Kernel profile, owner
+validator binding, and configured chain IDs. After authenticating pairing, a
+deployment calls `enrollOwnerDevice({ expectedRevision, device, accounts })` to
+register a phone and its new P-256 Kernel accounts atomically in one workspace.
+All accounts must bind that phone's same public owner key. Existing device or
+account identities cannot be overwritten; enrollment does not add membership.
+The deployment assigns the authenticated owner subject and separately issues
+relay credentials. The directory stores public account identity and routing,
+not private keys or bearer credentials.
+
+`resolveOwner(caller, request)` admits a canonical permission request only when
+its explicit workspace/account context, full account profile, and application
+match a current membership and registered account. It returns that account's
+owner-device route. Account selection is a preference, so changing it does not
+retarget requests from an existing connection. Membership removal refuses new
+requests; previously admitted requests retain their stored route.
+
+`read()` returns `{ revision, directory }` or `null`. Deployment administration
+replaces the document using that revision; `replace()` returns `false` if a
+concurrent writer won. `selectAccount(caller, { workspaceId, accountId })`
+checks membership and changes only that caller's selection, also returning
+`false` on a concurrent write. The deployment authenticates the caller before
+invoking this capability; it is not an open HTTP administration API.
+
+PostgreSQL stores one atomic document for the PoC. Each resolver reads current
+durable state; there is no process cache. An ambiguous write throws
+`relay_state_ambiguous` and is never retried automatically. The deployment owns
+pool shutdown. Membership/account removal can leave old selections behind;
+resolution checks current records and returns `null` rather than granting
+access through stale preferences. It does not revoke grants or delete operations.
+
+### Phone relay credentials
+
+`createOwnerDeviceAuthentication` from `@oaath/server/native` provides the phone
+part of the deployment's authentication port. Compose it with application
+identity authentication; it only returns owner callers.
+
+```ts
+import { createOwnerDeviceAuthentication } from "@oaath/server/native";
+import {
+  createPostgresOwnerDeviceCredentialSchema,
+  createPostgresOwnerDeviceCredentialStore,
+} from "@oaath/server/postgres";
+
+// Provision once, separately from the public directory and relay tables.
+await createPostgresOwnerDeviceCredentialSchema(pool);
+const phoneAuthentication = createOwnerDeviceAuthentication({
+  directory,
+  store: createPostgresOwnerDeviceCredentialStore({ pool }),
+});
+// Administration only: authenticate pairing and enroll this device first.
+const deviceCredential = await phoneAuthentication.issue({ workspaceId, ownerDeviceId });
+// Return it once to the paired phone; never log it.
+// Route phone requests through phoneAuthentication.authenticate(request).
+```
+
+The store retains only a SHA-256 hash and the workspace/device/subject binding
+under `oaath.owner-device-credential/v1`. The phone keeps the original 32-byte
+base64url bearer. Recreating the service and PostgreSQL pools preserves access
+with that bearer; authentication checks the current directory without a cache.
+Missing devices, changed subjects and explicitly revoked credentials cannot
+authenticate. Unreadable storage is an error.
+
+`phoneAuthentication.revoke({ workspaceId, ownerDeviceId })` terminally revokes
+all credentials already issued for that device. It does not revoke grants,
+uninstall permissions, remove enrollment or erase phone keys. A later explicit
+`issue` creates another credential; old revoked credentials remain unusable.
+Issuance and revocation never retry writes. A lost issuance response throws and
+returns no credential; the deployment owns pairing delivery and pool shutdown.
+This is credential persistence, not a durable pairing-invitation or full-service
+restart implementation. The demo uses `createMemoryOwnerDeviceCredentialStore`
+and remains ephemeral with its local chains.
+
 ## Endpoints
 
 ```text
@@ -31,20 +136,149 @@ POST /authorization/requests/{requestId}/decision  owner   approve or reject
 POST /authorization/codes/consume                  client  one-time code consume
 POST /authorization/artifacts/{artifactId}/claim   client  one-time artifact claim
 POST /authorization/resume                         client  fresh auth + recovery read
+POST /grants/verify                                client  grant reference verification
+POST /grants/{grantId}/revocations/{chainId}         client  request or recover phone custody
+GET  /grants/{grantId}/revocations/{chainId}         client  read current phone custody status
 ```
 
-EXPERIMENTAL PREVIEW routes (owner-phone approval; wire shapes pinned by the
-strict Swift decoders in `native/ios/Sources/OwnerPhone/`):
+EXPERIMENTAL PREVIEW routes (owner-phone approval):
 
 ```text
+GET  /native/inbox                                owner   pending consent summaries
 GET  /native/projections/{operationId}             owner   consent projection
+GET  /native/permission-signing/{operationId}      owner   prepared Kernel signing projection
 POST /native/decisions/{operationId}               owner   approve or reject saga
+POST /native/revocation-decisions/{operationId}    owner   revocation custody decision
 ```
 
+`GET /native/inbox` returns `oaath.native-inbox/v1` with `requests`, each containing
+only `operationId`, `displayPayload`, and `expiresAt` (epoch milliseconds).
+It reads existing permission and revocation requests for the authenticated owner,
+excluding expired or decided requests, and returns at most 20 ordered by expiry
+then operation ID. There is no separate inbox table or delivery flag to restore.
+PostgreSQL readers recover the list after service recreation. Listing does not
+prepare, sign, submit, or open an approval artifact; fetching consent checks
+current state again. The example phone uses this endpoint for its pull inbox.
+
+Canonical phone permission approval requires `RelayHandlerOptions.permissionApprovals`.
+Wire its `prepare(request)` to `prepareKernelPermissionApproval` from
+`@oaath/sdk/kernel`, supplying the deployment's account reads, chain ID, and
+stable install nonce for that request. Return the helper's `signingRequest`
+and a `complete(artifact, decidedAt)` that JSON-serializes its completion result.
+The approval handler holds no owner key. The phone reviews the permission,
+fetches its signing projection, and submits its P-256 artifact to the native
+decision route. That route completes the grant through the injected helper and
+the existing one-time decision transaction. A committed retry returns the stored
+outcome before invoking preparation. An unconfigured deployment cannot approve
+canonical permissions through the native route.
+
+Service-approved `grant.revoke()` posts an empty object to the grant/chain revocation
+route for each target without complete chain evidence. Configure
+`RelayHandlerOptions.revocations` with the service `directory` and a
+`prepare({ request, artifact, chainId })` capability. The existing
+`requestOwnerPhoneRevocation` entry from `@oaath/server/native` owns admission
+and durable custody. It checks the original application/member, resolves the
+configured account and phone, and opens the retained approval even after claim
+or execution-policy expiry. The deployment selects the effect, root nonce and
+gas from chain state and passes them, with the request, to
+`prepareKernelPermissionRevocation` from `@oaath/sdk/kernel`, returning its
+`signingRequest`. Preparation must not reserve
+a lane or nonce, sign, or submit; concurrent preparations may lose admission.
+
+POST returns `201` for new custody or `200` for recovered custody. GET creates
+nothing. Both return only `{ grantId, chainId, operationId, expiresAt, status }`,
+where status is `pending`, `approved`, `rejected`, or `expired`. Pending and
+terminal requests are recovered before preparation or KMS access, including
+after a lost response. An explicit POST may replace expired, undecided custody;
+approved and rejected requests remain terminal. No uncertain submission or
+expired approval authorizes a replacement operation.
+
+The paired phone fetches the shared projection route and posts approve/reject
+to `revocation-decisions`. PostgreSQL preserves the exact request and sealed
+phone artifact across restart. A repeated decision answers the stored outcome,
+even after expiry or a conflicting command. Approval acknowledges custody;
+the operation journal owns submission and finality. The client remains
+`revoking` until every saved target has finalized chain-effect evidence. The
+deployment still owns phone delivery and the execution worker. No OAuth code
+or artifact is released by revocation.
+
 Failures are `{"error":{"code":"relay_*"}}` with the status from
 `RELAY_ERROR_STATUS`. A response never carries message text, provider output, or
 internal detail.
 
+## Owner revocation execution
+
+`@oaath/server/kernel` composes approved phone custody with the SDK's existing
+OperationRunner, OperationStore and OperationObserver. Use
+`createOwnerPhoneRevocationExecutor({ store, kms, clock, operationId, operations,
+observation, submission })` in a deployment worker. `operations` is an SDK
+OperationStoreAdapter; `createPostgresOperationSchema` and
+`createPostgresOperationStoreAdapter({ pool })` from `@oaath/server/postgres`
+provide its durable implementation. Create the current operation tables once
+alongside the relay schema. The deployment owns the pool.
+
+`start(timeoutMs)` commits submission evidence before opening the deployment's
+`submission.openSubmission(prepared, signature)` capability. Opening returns
+`{ submit(), close() }` and must not send; the zero-argument submit sends only that
+snapshot. `observe(timeoutMs)` uses the existing observer's chain evidence.
+Recreating the executor preserves factory bytes, nonce, gas, calls and hash.
+An attempted or terminal operation is never submitted again; recovery works
+without KMS or submission access. Expired consent prevents a fresh attempt but
+never hides existing operation evidence. `close()` releases runner resources
+and can be retried after cleanup failure.
+
+Finalized operation success is evidence about that exact operation. The client separately observes permission absence and consumed install nonces
+on every saved revocation target. Automatic worker scheduling and replacement
+planning remain separate work. This subpath introduces the server's explicit
+SDK dependency; the relay root imports no runtime or PostgreSQL driver.
+
+## Grant reference verification
+
+`POST /grants/verify` lets an integrating application bind an immutable
+artifact of its own (for example a reviewed deployment run) to the exact
+authority revision that approved a Grant. The body is a
+`VerifyGrantRevisionInput` and the `200` response is a
+`GrantVerificationResult`, both owned by `@oaath/protocol`
+(`parseGrantVerificationResult` must parse every response before it is acted
+on). Every field in the body is an assertion compared against the relay's
+durable authorization evidence — never trusted as identity — and the result is
+`authorized` (with the immutable `OaathGrantRef`), `denied`, or `unknown`,
+each with a typed code. Unreadable or absent evidence answers `unknown` and
+never authorizes. Verification is a pure read: it is replay-safe and mutates
+nothing.
+
+How an application organization/audience maps to the OAAth client/realm:
+
+- One deployed relay URL can serve multiple personal and team workspaces.
+  `bootstrap.resolve(caller)` selects the caller's workspace, logical account,
+  and configured chains on each request. The SDK keeps local realms separate
+  by caller, workspace/account context, and complete account profile. The service
+  directory provides the versioned membership and account selection records.
+- `clientId`, the pairwise `subject`, and the `organizationAudience` are all
+  asserted by the deployment's `RelayAuthentication` port. An application
+  backend with its own cookie session obtains an authenticated OAAth caller by
+  implementing that port — its handler reads its own session and returns the
+  `RelayCaller` bindings — so no session policy is ever copied out of the
+  deployment.
+- The audience is captured onto the authorization request when the Grant is
+  requested. Verification denies any audience assertion that does not match
+  the captured value; a deployment that declares no audiences therefore never
+  verifies one.
+- `revision` is the approved authority revision. OAAth Grant authority is
+  immutable per Grant (an authority change is a revocation plus a new Grant),
+  so the single approval is revision `1`; anything else denies.
+- `requiredCallsDigest` is `hashGrantPolicyCalls` over the reviewed call set
+  and must equal the sealed approval's exact approved call set. `policyDigest`
+  is `hashGrantPolicy(approvedPolicy)`, which may differ from the requested
+  policy in the Grant identity. The approved expiry also bounds verification.
+- Verification reads the retained encrypted artifact by request ID and checks
+  its permission decision's request binding and policy attenuation. An approved
+  OAuth outcome alone is insufficient; missing or unreadable approval evidence,
+  including unavailable KMS, returns `unknown/grant_unreadable`. Reading never
+  consumes a code or claims/releases an artifact, including after client claim
+  and process restart. This verifies service-approved authority; it does not
+  prove onchain installation or replace the Kernel runtime's capability checks.
+
 ## Security notes
 
 - The approving decision, the authorization code, and the encrypted artifact are
@@ -66,15 +300,15 @@ internal detail.
 ## Schema
 
 `createPostgresRelaySchema` creates the one current schema
-(`oaath.relay-postgres-schema/v1`). There is no migration runner: an obsolete
+(`oaath.relay-postgres-schema/v4`). There is no migration runner: an obsolete
 database is dropped and recreated.
 
 ## Tests
 
-Ordinary local `pnpm test` never contacts a database. The default repository CI
+Ordinary local `bun run test` never contacts a database. The default repository CI
 runs the PostgreSQL and restart proofs against its job-local service. Reproduce
 that gate locally with an explicit opt-in:
 
 ```sh
-OAATH_REQUIRE_POSTGRES=1 OAATH_POSTGRES_URL=postgres://localhost:5432/postgres pnpm test:postgres
+OAATH_REQUIRE_POSTGRES=1 OAATH_POSTGRES_URL=postgres://localhost:5432/postgres bun run test:postgres
 ```

package/dist/apns.d.ts

@@ -1,5 +1,5 @@
-import { i as RelayClock } from "./authentication-HUYWk5Y2.js";
-import { r as OwnerPhonePushProjection } from "./projection-g6k_CCUK.js";
+import { b as RelayClock } from "./interface-DHpwP0wr.js";
+import { n as OwnerPhonePushProjection } from "./projection-B7IB9irs.js";
 //#region src/apns/sender.d.ts
 /** Apple's hard limit for an alert notification payload. */
 declare const APNS_PAYLOAD_MAX_BYTES = 4096;

package/dist/apns.js

@@ -1,5 +1,5 @@
-import { b as relayFailure, c as canonicalIdentifier, m as timestamp, s as boundedText } from "./records-Bgr-9PUh.js";
-import { a as relayNow, n as randomIdentifier } from "./challenge-AGTmUfj2.js";
+import { b as relayFailure, c as canonicalIdentifier, m as timestamp, s as boundedText } from "./records-BQNDxbPg.js";
+import { a as relayNow, n as randomIdentifier } from "./challenge-DmpGSogj.js";
 import { exactRecord } from "@oaath/protocol";
 import { createPrivateKey, sign } from "node:crypto";
 //#region src/apns/sender.ts

package/dist/{challenge-AGTmUfj2.js → challenge-DmpGSogj.js}

@@ -1,4 +1,4 @@
-import { b as relayFailure, m as timestamp } from "./records-Bgr-9PUh.js";
+import { b as relayFailure, m as timestamp } from "./records-BQNDxbPg.js";
 //#region src/clock.ts
 /**
 * Injected clock. Expiry is never read from `Date.now()` directly, so tests and
@@ -68,4 +68,4 @@ function isCodeChallengeS256(value) {
 //#endregion
 export { relayNow as a, verifyPkceS256 as i, randomIdentifier as n, sha256Base64Url as r, isCodeChallengeS256 as t };
 
-//# sourceMappingURL=challenge-AGTmUfj2.js.map
+//# sourceMappingURL=challenge-DmpGSogj.js.map

package/dist/{challenge-AGTmUfj2.js.map → challenge-DmpGSogj.js.map}

@@ -1 +1 @@
-{"version":3,"file":"challenge-AGTmUfj2.js","names":[],"sources":["../src/clock.ts","../src/authorization/challenge.ts"],"sourcesContent":["/**\n * Injected clock. Expiry is never read from `Date.now()` directly, so tests and\n * deployments own time.\n *\n * @author taek <leekt216@gmail.com>\n */\n\nimport { relayFailure } from \"./relay/errors.js\";\nimport { timestamp } from \"./store/records.js\";\n\nexport interface RelayClock {\n  /** Milliseconds since the Unix epoch as a non-negative safe integer. */\n  now(): number;\n}\n\nexport function relayNow(clock: RelayClock): number {\n  let value: unknown;\n  try {\n    value = clock.now();\n  } catch {\n    return relayFailure(\"relay_internal\", \"injected clock failed\");\n  }\n  return timestamp(value, \"clock time\", \"relay_internal\");\n}\n","/**\n * PKCE S256 challenge verification and the relay's random/digest primitives.\n *\n * Only WebCrypto and base64url are used, so this file stays platform-neutral.\n * The verifier is never stored: the store holds the S256 challenge, and consume\n * recomputes it.\n *\n * @author taek <leekt216@gmail.com>\n */\n\nimport { relayFailure } from \"../relay/errors.js\";\n\n/** RFC 7636 code verifier: 43-128 unreserved characters. */\nconst CODE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/u;\n\nconst IDENTIFIER_BYTES = 32;\n\nfunction base64Url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary).replaceAll(\"+\", \"-\").replaceAll(\"/\", \"_\").replaceAll(\"=\", \"\");\n}\n\n/** 256 bits of CSPRNG output, base64url encoded. */\nexport function randomIdentifier(): string {\n  return base64Url(crypto.getRandomValues(new Uint8Array(IDENTIFIER_BYTES)));\n}\n\nexport async function sha256Base64Url(value: string): Promise<string> {\n  let digest: ArrayBuffer;\n  try {\n    digest = await crypto.subtle.digest(\"SHA-256\", new TextEncoder().encode(value));\n  } catch {\n    return relayFailure(\"relay_internal\", \"WebCrypto SHA-256 is unavailable\");\n  }\n  return base64Url(new Uint8Array(digest));\n}\n\nfunction timingSafeEqualText(left: string, right: string): boolean {\n  // Both operands are base64url digests, so length is not itself a secret.\n  if (left.length !== right.length) return false;\n  let difference = 0;\n  for (let index = 0; index < left.length; index += 1) {\n    difference |= left.charCodeAt(index) ^ right.charCodeAt(index);\n  }\n  return difference === 0;\n}\n\n/**\n * True only when `codeVerifier` is a well-formed RFC 7636 verifier whose S256\n * digest equals the stored challenge. Any malformed input is a mismatch.\n */\nexport async function verifyPkceS256(\n  codeVerifier: string,\n  storedCodeChallenge: string,\n): Promise<boolean> {\n  if (!CODE_VERIFIER.test(codeVerifier)) return false;\n  return timingSafeEqualText(await sha256Base64Url(codeVerifier), storedCodeChallenge);\n}\n\n/** True when the value can be a stored S256 challenge (43 base64url characters). */\nexport function isCodeChallengeS256(value: string): boolean {\n  return /^[A-Za-z0-9_-]{43}$/u.test(value);\n}\n"],"mappings":";;;;;;;;AAeA,SAAgB,SAAS,OAA2B;CAClD,IAAI;CACJ,IAAI;EACF,QAAQ,MAAM,IAAI;CACpB,QAAQ;EACN,OAAO,aAAa,kBAAkB,uBAAuB;CAC/D;CACA,OAAO,UAAU,OAAO,cAAc,gBAAgB;AACxD;;;;;;;;;;;;;ACVA,MAAM,gBAAgB;AAEtB,MAAM,mBAAmB;AAEzB,SAAS,UAAU,OAA2B;CAC5C,IAAI,SAAS;CACb,KAAK,MAAM,QAAQ,OAAO,UAAU,OAAO,aAAa,IAAI;CAC5D,OAAO,KAAK,MAAM,CAAC,CAAC,WAAW,KAAK,GAAG,CAAC,CAAC,WAAW,KAAK,GAAG,CAAC,CAAC,WAAW,KAAK,EAAE;AAClF;;AAGA,SAAgB,mBAA2B;CACzC,OAAO,UAAU,OAAO,gBAAgB,IAAI,WAAW,gBAAgB,CAAC,CAAC;AAC3E;AAEA,eAAsB,gBAAgB,OAAgC;CACpE,IAAI;CACJ,IAAI;EACF,SAAS,MAAM,OAAO,OAAO,OAAO,WAAW,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,CAAC;CAChF,QAAQ;EACN,OAAO,aAAa,kBAAkB,kCAAkC;CAC1E;CACA,OAAO,UAAU,IAAI,WAAW,MAAM,CAAC;AACzC;AAEA,SAAS,oBAAoB,MAAc,OAAwB;CAEjE,IAAI,KAAK,WAAW,MAAM,QAAQ,OAAO;CACzC,IAAI,aAAa;CACjB,KAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS,GAChD,cAAc,KAAK,WAAW,KAAK,IAAI,MAAM,WAAW,KAAK;CAE/D,OAAO,eAAe;AACxB;;;;;AAMA,eAAsB,eACpB,cACA,qBACkB;CAClB,IAAI,CAAC,cAAc,KAAK,YAAY,GAAG,OAAO;CAC9C,OAAO,oBAAoB,MAAM,gBAAgB,YAAY,GAAG,mBAAmB;AACrF;;AAGA,SAAgB,oBAAoB,OAAwB;CAC1D,OAAO,uBAAuB,KAAK,KAAK;AAC1C"}
+{"version":3,"file":"challenge-DmpGSogj.js","names":[],"sources":["../src/clock.ts","../src/authorization/challenge.ts"],"sourcesContent":["/**\n * Injected clock. Expiry is never read from `Date.now()` directly, so tests and\n * deployments own time.\n *\n * @author taek <leekt216@gmail.com>\n */\n\nimport { relayFailure } from \"./relay/errors.js\";\nimport { timestamp } from \"./store/records.js\";\n\nexport interface RelayClock {\n  /** Milliseconds since the Unix epoch as a non-negative safe integer. */\n  now(): number;\n}\n\nexport function relayNow(clock: RelayClock): number {\n  let value: unknown;\n  try {\n    value = clock.now();\n  } catch {\n    return relayFailure(\"relay_internal\", \"injected clock failed\");\n  }\n  return timestamp(value, \"clock time\", \"relay_internal\");\n}\n","/**\n * PKCE S256 challenge verification and the relay's random/digest primitives.\n *\n * Only WebCrypto and base64url are used, so this file stays platform-neutral.\n * The verifier is never stored: the store holds the S256 challenge, and consume\n * recomputes it.\n *\n * @author taek <leekt216@gmail.com>\n */\n\nimport { relayFailure } from \"../relay/errors.js\";\n\n/** RFC 7636 code verifier: 43-128 unreserved characters. */\nconst CODE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/u;\n\nconst IDENTIFIER_BYTES = 32;\n\nfunction base64Url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary).replaceAll(\"+\", \"-\").replaceAll(\"/\", \"_\").replaceAll(\"=\", \"\");\n}\n\n/** 256 bits of CSPRNG output, base64url encoded. */\nexport function randomIdentifier(): string {\n  return base64Url(crypto.getRandomValues(new Uint8Array(IDENTIFIER_BYTES)));\n}\n\nexport async function sha256Base64Url(value: string): Promise<string> {\n  let digest: ArrayBuffer;\n  try {\n    digest = await crypto.subtle.digest(\"SHA-256\", new TextEncoder().encode(value));\n  } catch {\n    return relayFailure(\"relay_internal\", \"WebCrypto SHA-256 is unavailable\");\n  }\n  return base64Url(new Uint8Array(digest));\n}\n\nfunction timingSafeEqualText(left: string, right: string): boolean {\n  // Both operands are base64url digests, so length is not itself a secret.\n  if (left.length !== right.length) return false;\n  let difference = 0;\n  for (let index = 0; index < left.length; index += 1) {\n    difference |= left.charCodeAt(index) ^ right.charCodeAt(index);\n  }\n  return difference === 0;\n}\n\n/**\n * True only when `codeVerifier` is a well-formed RFC 7636 verifier whose S256\n * digest equals the stored challenge. Any malformed input is a mismatch.\n */\nexport async function verifyPkceS256(\n  codeVerifier: string,\n  storedCodeChallenge: string,\n): Promise<boolean> {\n  if (!CODE_VERIFIER.test(codeVerifier)) return false;\n  return timingSafeEqualText(await sha256Base64Url(codeVerifier), storedCodeChallenge);\n}\n\n/** True when the value can be a stored S256 challenge (43 base64url characters). */\nexport function isCodeChallengeS256(value: string): boolean {\n  return /^[A-Za-z0-9_-]{43}$/u.test(value);\n}\n"],"mappings":";;;;;;;;AAeA,SAAgB,SAAS,OAA2B;CAClD,IAAI;CACJ,IAAI;EACF,QAAQ,MAAM,IAAI;CACpB,QAAQ;EACN,OAAO,aAAa,kBAAkB,uBAAuB;CAC/D;CACA,OAAO,UAAU,OAAO,cAAc,gBAAgB;AACxD;;;;;;;;;;;;;ACVA,MAAM,gBAAgB;AAEtB,MAAM,mBAAmB;AAEzB,SAAS,UAAU,OAA2B;CAC5C,IAAI,SAAS;CACb,KAAK,MAAM,QAAQ,OAAO,UAAU,OAAO,aAAa,IAAI;CAC5D,OAAO,KAAK,MAAM,CAAC,CAAC,WAAW,KAAK,GAAG,CAAC,CAAC,WAAW,KAAK,GAAG,CAAC,CAAC,WAAW,KAAK,EAAE;AAClF;;AAGA,SAAgB,mBAA2B;CACzC,OAAO,UAAU,OAAO,gBAAgB,IAAI,WAAW,gBAAgB,CAAC,CAAC;AAC3E;AAEA,eAAsB,gBAAgB,OAAgC;CACpE,IAAI;CACJ,IAAI;EACF,SAAS,MAAM,OAAO,OAAO,OAAO,WAAW,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,CAAC;CAChF,QAAQ;EACN,OAAO,aAAa,kBAAkB,kCAAkC;CAC1E;CACA,OAAO,UAAU,IAAI,WAAW,MAAM,CAAC;AACzC;AAEA,SAAS,oBAAoB,MAAc,OAAwB;CAEjE,IAAI,KAAK,WAAW,MAAM,QAAQ,OAAO;CACzC,IAAI,aAAa;CACjB,KAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS,GAChD,cAAc,KAAK,WAAW,KAAK,IAAI,MAAM,WAAW,KAAK;CAE/D,OAAO,eAAe;AACxB;;;;;AAMA,eAAsB,eACpB,cACA,qBACkB;CAClB,IAAI,CAAC,cAAc,KAAK,YAAY,GAAG,OAAO;CAC9C,OAAO,oBAAoB,MAAM,gBAAgB,YAAY,GAAG,mBAAmB;AACrF;;AAGA,SAAgB,oBAAoB,OAAwB;CAC1D,OAAO,uBAAuB,KAAK,KAAK;AAC1C"}

package/dist/inbox-B80EUVht.js

@@ -0,0 +1,249 @@
+import { b as relayFailure, h as OaathRelayError, n as OAATH_AUTHORIZATION_DECISION_RECORD_VERSION } from "./records-BQNDxbPg.js";
+import { a as relayNow, n as randomIdentifier, r as sha256Base64Url } from "./challenge-DmpGSogj.js";
+import { S as withRelayTransaction, _ as verifyKernelV4ReplayableInstallOwnerSigningArtifact, d as classifyStoredAuthorizationScope, g as ownerPhoneDisplayPayload, p as fetchAuthorizationRequest, u as prepareOwnerPhonePermissionApproval, v as parseApprovedPermission, x as sealArtifact } from "./service-Cf4f-9KP.js";
+import { parseOwnerSigningArtifact } from "@oaath/protocol";
+//#region src/authorization/decision.ts
+/**
+* Authoritative approve/reject transition.
+*
+* ```text
+* state and owner        the decision record owns "decided"; the request record
+*                        never mutates
+* persisted evidence     the immutable requestedScope is reclassified from the
+*                        durable request before every approval attempt; the
+*                        artifact must carry its valid bound approval
+* resource occupied?     a refused approval occupies nothing and performs no KMS
+*                        sealing; a rejection occupies only its decision row
+* retry positively safe? refused approval is read-only; a terminal outcome is
+*                        replayed by the native saga and rejected by this owner
+* transitions            permission or verified Kernel owner signing:
+*                        undecided -> approved | rejected;
+*                        every reject-only scope: undecided -> rejected once
+* terminal               both outcomes; a second decide fails relay_already_decided
+* crash/reload           the decision, the code, and the sealed artifact commit in
+*                        one transaction on the row-locked request, so a crash
+*                        leaves the request undecided and nothing released
+* cleanup owner          the relay transaction; refused approvals allocate nothing
+* ```
+*
+* Owner binding: the approving subject is recovered from the stored
+* authorization request by `requestId` and compared against the authenticated
+* owner. No wire field names the subject. A decision envelope that carries a
+* subject identifier is rejected as an unknown field by exact capture, because a
+* field that only *names* a subject is not cryptographically bound to it and can
+* never decide authority.
+*
+* @author taek <leekt216@gmail.com>
+*/
+async function submitAuthorizationDecision(input) {
+	const decidedAt = relayNow(input.clock);
+	let approvedArtifact;
+	if (input.command.outcome === "approved") {
+		const state = await fetchAuthorizationRequest({
+			store: input.store,
+			clock: input.clock,
+			caller: input.caller,
+			requestId: input.requestId
+		});
+		if (state.decision !== null) return relayFailure("relay_already_decided", "authorization request is already decided");
+		if (state.expired) return relayFailure("relay_expired", "authorization request expired");
+		const scope = classifyStoredAuthorizationScope(state.requestedScope, state.requestId);
+		if (scope.kind === "permission-request") try {
+			approvedArtifact = parseApprovedPermission(input.command.artifact, scope.request, decidedAt).plaintext;
+		} catch {
+			return relayFailure("relay_request_invalid", "permission approval artifact is invalid");
+		}
+		else if (scope.kind === "kernel-owner-signing-request") approvedArtifact = verifyKernelV4ReplayableInstallOwnerSigningArtifact(scope.request, input.command.artifact);
+		else return relayFailure("relay_request_invalid", "the authorization scope is reject-only");
+	}
+	let approved;
+	if (input.command.outcome === "approved") {
+		if (approvedArtifact === void 0) return relayFailure("relay_internal", "approved artifact was not authorized");
+		const code = randomIdentifier();
+		approved = Object.freeze({
+			code,
+			artifactId: randomIdentifier(),
+			ciphertextRef: await sealArtifact(input.kms, approvedArtifact),
+			codeRef: await sealArtifact(input.kms, code)
+		});
+	}
+	const codeHash = approved ? await sha256Base64Url(approved.code) : void 0;
+	const decision = Object.freeze({
+		version: OAATH_AUTHORIZATION_DECISION_RECORD_VERSION,
+		requestId: input.requestId,
+		outcome: input.command.outcome,
+		decidedAt,
+		codeRef: approved?.codeRef ?? null,
+		codeExpiresAt: approved ? decidedAt + input.codeTtlMs : null
+	});
+	const redirectUri = await withRelayTransaction(input.store, async (transaction) => {
+		const request = await transaction.lockAuthorizationRequest(input.requestId);
+		if (!request || request.ownerSubject !== input.caller.subject) return relayFailure("relay_not_found", "authorization request does not exist");
+		if (await transaction.lockAuthorizationDecision(input.requestId)) return relayFailure("relay_already_decided", "authorization request is already decided");
+		if (decidedAt >= request.expiresAt) return relayFailure("relay_expired", "authorization request expired");
+		if (!await transaction.insertAuthorizationDecision(decision)) return relayFailure("relay_already_decided", "authorization request is already decided");
+		if (approved && codeHash !== void 0) {
+			if (!(await transaction.insertAuthorizationCode(Object.freeze({
+				version: "oaath.authorization-code-record/v1",
+				codeHash,
+				requestId: request.requestId,
+				clientId: request.clientId,
+				redirectUri: request.redirectUri,
+				codeChallenge: request.codeChallenge,
+				artifactId: approved.artifactId,
+				createdAt: decidedAt,
+				expiresAt: decidedAt + input.codeTtlMs,
+				consumedAt: null
+			})) && await transaction.insertEncryptedArtifact(Object.freeze({
+				version: "oaath.encrypted-artifact-record/v1",
+				artifactId: approved.artifactId,
+				requestId: request.requestId,
+				clientId: request.clientId,
+				ciphertextRef: approved.ciphertextRef,
+				createdAt: decidedAt,
+				claimedAt: null
+			})))) return relayFailure("relay_internal", "released identifier is not unique");
+		}
+		return request.redirectUri;
+	});
+	if (approved && codeHash !== void 0) return Object.freeze({
+		outcome: "approved",
+		decidedAt,
+		code: approved.code,
+		artifactId: approved.artifactId,
+		redirectUri,
+		codeExpiresAt: decidedAt + input.codeTtlMs
+	});
+	return Object.freeze({
+		outcome: "rejected",
+		decidedAt
+	});
+}
+//#endregion
+//#region src/native/decision.ts
+/**
+* EXPERIMENTAL PREVIEW — approve/reject saga keyed by the stable operation id.
+*
+* ```text
+* state and owner        the relay's authorization decision record. This saga
+*                        owns no decision state of its own and keeps nothing in
+*                        memory; it routes to `submitAuthorizationDecision`.
+* persisted evidence     one terminal decision row per request
+* resource occupied?     yes: the decision occupies its request, and the
+*                        one-time code and artifact are released exactly once
+* retry positively safe? yes for the saga call, because a repeated call never
+*                        decides again: it answers the stored outcome
+* transitions            undecided -> approved | rejected once, then replay-only
+* crash/reload           the outcome is durable before the caller sees it, so a
+*                        phone that never saw its response retries and is
+*                        answered from the store, on any process
+* cleanup owner          the relay transaction; nothing extra is allocated here
+* ```
+*
+* A second decide answers the *stored* outcome, not the resubmitted command: if
+* a rejected request is retried as approved, the answer is `rejected`. Compare
+* `outcome` against what you sent when that matters.
+*
+* The one-time code and encrypted artifact are released to the deciding call
+* only. A replay reports the outcome and no release material, because releasing
+* it twice is exactly what one-shot semantics forbid.
+*
+* @author taek <leekt216@gmail.com>
+*/
+async function submitOwnerPhoneDecision(input) {
+	if (input.caller.role !== "owner") return relayFailure("relay_forbidden", "caller may not act in the required role");
+	const pending = await fetchAuthorizationRequest({
+		...input,
+		requestId: input.operationId
+	});
+	if (pending.decision !== null) return Object.freeze({
+		operationId: input.operationId,
+		outcome: pending.decision.outcome,
+		decidedAt: pending.decision.decidedAt,
+		settlement: "replayed",
+		release: null
+	});
+	let command = input.command;
+	if (command.outcome === "approved" && !pending.expired) {
+		const scope = classifyStoredAuthorizationScope(pending.requestedScope, pending.requestId);
+		if (scope.kind === "permission-request") {
+			const prepared = await prepareOwnerPhonePermissionApproval(input.permissionApprovals, scope.request);
+			let artifact;
+			try {
+				artifact = parseOwnerSigningArtifact(JSON.parse(command.artifact));
+			} catch {
+				return relayFailure("relay_request_invalid", "phone signing artifact is invalid");
+			}
+			command = {
+				outcome: "approved",
+				artifact: await prepared.complete(artifact, Math.floor(relayNow(input.clock) / 1e3))
+			};
+		}
+	}
+	try {
+		const release = await submitAuthorizationDecision({
+			store: input.store,
+			clock: input.clock,
+			kms: input.kms,
+			caller: input.caller,
+			requestId: input.operationId,
+			command,
+			codeTtlMs: input.codeTtlMs
+		});
+		return Object.freeze({
+			operationId: input.operationId,
+			outcome: release.outcome,
+			decidedAt: release.decidedAt,
+			settlement: "decided",
+			release
+		});
+	} catch (error) {
+		if (!(error instanceof OaathRelayError) || error.code !== "relay_already_decided") throw error;
+	}
+	const state = await fetchAuthorizationRequest({
+		store: input.store,
+		clock: input.clock,
+		caller: input.caller,
+		requestId: input.operationId
+	});
+	if (state.decision === null) return relayFailure("relay_internal", "decided request has no decision record");
+	return Object.freeze({
+		operationId: input.operationId,
+		outcome: state.decision.outcome,
+		decidedAt: state.decision.decidedAt,
+		settlement: "replayed",
+		release: null
+	});
+}
+//#endregion
+//#region src/native/inbox.ts
+/**
+* Read-only owner inbox derived from retained relay requests and decisions.
+* No delivery state, lease or second queue is persisted. Recreating the service
+* reads the same pending requests; deciding or expiring one removes it from the
+* next listing. A summary is discovery only: consent/decision checks current state.
+*/
+const OAATH_NATIVE_INBOX_VERSION = "oaath.native-inbox/v1";
+const INBOX_LIMIT = 20;
+/** The store owns transaction resources; this read prepares, signs and submits nothing. */
+async function listOwnerPhoneRequests(input) {
+	if (input.caller.role !== "owner") return relayFailure("relay_forbidden", "only an owner may read the inbox");
+	const now = relayNow(input.clock);
+	const requests = await withRelayTransaction(input.store, (transaction) => transaction.listPendingOwnerRequests(input.caller.subject, now, INBOX_LIMIT));
+	if (requests.length > INBOX_LIMIT) return relayFailure("relay_record_unreadable", "owner inbox is unbounded");
+	return Object.freeze({
+		version: OAATH_NATIVE_INBOX_VERSION,
+		requests: Object.freeze(await Promise.all(requests.map(async (request) => {
+			if (request.ownerSubject !== input.caller.subject || request.expiresAt <= now) return relayFailure("relay_record_unreadable", "pending request does not match this owner inbox");
+			return Object.freeze({
+				operationId: request.operationId,
+				expiresAt: request.expiresAt,
+				displayPayload: await ownerPhoneDisplayPayload(request.ownerSubject, request.operationId)
+			});
+		})))
+	});
+}
+//#endregion
+export { submitAuthorizationDecision as i, listOwnerPhoneRequests as n, submitOwnerPhoneDecision as r, OAATH_NATIVE_INBOX_VERSION as t };
+
+//# sourceMappingURL=inbox-B80EUVht.js.map

package/dist/inbox-B80EUVht.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox-B80EUVht.js","names":[],"sources":["../src/authorization/decision.ts","../src/native/decision.ts","../src/native/inbox.ts"],"sourcesContent":["/**\n * Authoritative approve/reject transition.\n *\n * ```text\n * state and owner        the decision record owns \"decided\"; the request record\n *                        never mutates\n * persisted evidence     the immutable requestedScope is reclassified from the\n *                        durable request before every approval attempt; the\n *                        artifact must carry its valid bound approval\n * resource occupied?     a refused approval occupies nothing and performs no KMS\n *                        sealing; a rejection occupies only its decision row\n * retry positively safe? refused approval is read-only; a terminal outcome is\n *                        replayed by the native saga and rejected by this owner\n * transitions            permission or verified Kernel owner signing:\n *                        undecided -> approved | rejected;\n *                        every reject-only scope: undecided -> rejected once\n * terminal               both outcomes; a second decide fails relay_already_decided\n * crash/reload           the decision, the code, and the sealed artifact commit in\n *                        one transaction on the row-locked request, so a crash\n *                        leaves the request undecided and nothing released\n * cleanup owner          the relay transaction; refused approvals allocate nothing\n * ```\n *\n * Owner binding: the approving subject is recovered from the stored\n * authorization request by `requestId` and compared against the authenticated\n * owner. No wire field names the subject. A decision envelope that carries a\n * subject identifier is rejected as an unknown field by exact capture, because a\n * field that only *names* a subject is not cryptographically bound to it and can\n * never decide authority.\n *\n * @author taek <leekt216@gmail.com>\n */\n\nimport { sealArtifact } from \"../artifact/encrypt.js\";\nimport { type RelayClock, relayNow } from \"../clock.js\";\nimport { relayFailure } from \"../relay/errors.js\";\nimport type { RelayCaller } from \"../security/authentication.js\";\nimport type { RelayKms } from \"../security/kms.js\";\nimport type { RelayStore } from \"../store/interface.js\";\nimport { withRelayTransaction } from \"../store/interface.js\";\nimport {\n  OAATH_AUTHORIZATION_CODE_RECORD_VERSION,\n  OAATH_AUTHORIZATION_DECISION_RECORD_VERSION,\n  OAATH_ENCRYPTED_ARTIFACT_RECORD_VERSION,\n} from \"../store/records.js\";\nimport { parseApprovedPermission } from \"./approved-permission.js\";\nimport { randomIdentifier, sha256Base64Url } from \"./challenge.js\";\nimport { verifyKernelV4ReplayableInstallOwnerSigningArtifact } from \"./owner-signing.js\";\nimport { fetchAuthorizationRequest } from \"./request.js\";\nimport { classifyStoredAuthorizationScope } from \"./scope.js\";\n\nexport type AuthorizationDecisionCommand =\n  /** The owner supplies a request-bound approval artifact; the client claims it once. */\n  Readonly<{ outcome: \"approved\"; artifact: string }> | Readonly<{ outcome: \"rejected\" }>;\n\nexport interface SubmitAuthorizationDecisionInput {\n  readonly store: RelayStore;\n  readonly clock: RelayClock;\n  readonly kms: RelayKms;\n  /** Authenticated `owner` caller; only the bound subject may decide. */\n  readonly caller: RelayCaller;\n  readonly requestId: string;\n  readonly command: AuthorizationDecisionCommand;\n  readonly codeTtlMs: number;\n}\n\nexport type SubmittedAuthorizationDecision =\n  | Readonly<{\n      outcome: \"approved\";\n      decidedAt: number;\n      /** Released exactly once, here. Only its SHA-256 is stored. */\n      code: string;\n      artifactId: string;\n      redirectUri: string;\n      codeExpiresAt: number;\n    }>\n  | Readonly<{ outcome: \"rejected\"; decidedAt: number }>;\n\nexport async function submitAuthorizationDecision(\n  input: SubmitAuthorizationDecisionInput,\n): Promise<SubmittedAuthorizationDecision> {\n  const decidedAt = relayNow(input.clock);\n  let approvedArtifact: string | undefined;\n\n  // Approval is the artifact-creating transition, so the shared decision owner\n  // admits it only for an exact scope this server currently permits to release.\n  // Refusal happens before KMS sealing or any durable decision/code/artifact.\n  if (input.command.outcome === \"approved\") {\n    const state = await fetchAuthorizationRequest({\n      store: input.store,\n      clock: input.clock,\n      caller: input.caller,\n      requestId: input.requestId,\n    });\n    // Preserve the transaction owner's existing precedence: the native saga\n    // must recover an earlier terminal outcome without reclassifying its scope.\n    if (state.decision !== null) {\n      return relayFailure(\"relay_already_decided\", \"authorization request is already decided\");\n    }\n    if (state.expired) {\n      return relayFailure(\"relay_expired\", \"authorization request expired\");\n    }\n    const scope = classifyStoredAuthorizationScope(state.requestedScope, state.requestId);\n    if (scope.kind === \"permission-request\") {\n      try {\n        approvedArtifact = parseApprovedPermission(\n          input.command.artifact,\n          scope.request,\n          decidedAt,\n        ).plaintext;\n      } catch {\n        return relayFailure(\"relay_request_invalid\", \"permission approval artifact is invalid\");\n      }\n    } else if (scope.kind === \"kernel-owner-signing-request\") {\n      approvedArtifact = verifyKernelV4ReplayableInstallOwnerSigningArtifact(\n        scope.request,\n        input.command.artifact,\n      );\n    } else {\n      return relayFailure(\"relay_request_invalid\", \"the authorization scope is reject-only\");\n    }\n  }\n\n  // Seal before the transaction: the store only ever receives references, and\n  // an uncommitted decision leaves nothing but unreferenced ciphertexts. The\n  // code is sealed too so the authenticated client can pick it up later; PKCE\n  // still guards its consumption.\n  let approved:\n    | Readonly<{ code: string; artifactId: string; ciphertextRef: string; codeRef: string }>\n    | undefined;\n  if (input.command.outcome === \"approved\") {\n    if (approvedArtifact === undefined) {\n      return relayFailure(\"relay_internal\", \"approved artifact was not authorized\");\n    }\n    const code = randomIdentifier();\n    approved = Object.freeze({\n      code,\n      artifactId: randomIdentifier(),\n      ciphertextRef: await sealArtifact(input.kms, approvedArtifact),\n      codeRef: await sealArtifact(input.kms, code),\n    });\n  }\n  const codeHash = approved ? await sha256Base64Url(approved.code) : undefined;\n  const decision = Object.freeze({\n    version: OAATH_AUTHORIZATION_DECISION_RECORD_VERSION,\n    requestId: input.requestId,\n    outcome: input.command.outcome,\n    decidedAt,\n    codeRef: approved?.codeRef ?? null,\n    codeExpiresAt: approved ? decidedAt + input.codeTtlMs : null,\n  } as const);\n\n  const redirectUri = await withRelayTransaction(input.store, async (transaction) => {\n    const request = await transaction.lockAuthorizationRequest(input.requestId);\n    // The request snapshots its approving subject independently of its requester.\n    if (!request || request.ownerSubject !== input.caller.subject) {\n      return relayFailure(\"relay_not_found\", \"authorization request does not exist\");\n    }\n    if (await transaction.lockAuthorizationDecision(input.requestId)) {\n      return relayFailure(\"relay_already_decided\", \"authorization request is already decided\");\n    }\n    if (decidedAt >= request.expiresAt) {\n      return relayFailure(\"relay_expired\", \"authorization request expired\");\n    }\n    if (!(await transaction.insertAuthorizationDecision(decision))) {\n      return relayFailure(\"relay_already_decided\", \"authorization request is already decided\");\n    }\n    if (approved && codeHash !== undefined) {\n      const inserted =\n        (await transaction.insertAuthorizationCode(\n          Object.freeze({\n            version: OAATH_AUTHORIZATION_CODE_RECORD_VERSION,\n            codeHash,\n            requestId: request.requestId,\n            clientId: request.clientId,\n            redirectUri: request.redirectUri,\n            codeChallenge: request.codeChallenge,\n            artifactId: approved.artifactId,\n            createdAt: decidedAt,\n            expiresAt: decidedAt + input.codeTtlMs,\n            consumedAt: null,\n          }),\n        )) &&\n        (await transaction.insertEncryptedArtifact(\n          Object.freeze({\n            version: OAATH_ENCRYPTED_ARTIFACT_RECORD_VERSION,\n            artifactId: approved.artifactId,\n            requestId: request.requestId,\n            clientId: request.clientId,\n            ciphertextRef: approved.ciphertextRef,\n            createdAt: decidedAt,\n            claimedAt: null,\n          }),\n        ));\n      if (!inserted) {\n        return relayFailure(\"relay_internal\", \"released identifier is not unique\");\n      }\n    }\n    return request.redirectUri;\n  });\n\n  if (approved && codeHash !== undefined) {\n    return Object.freeze({\n      outcome: \"approved\",\n      decidedAt,\n      code: approved.code,\n      artifactId: approved.artifactId,\n      redirectUri,\n      codeExpiresAt: decidedAt + input.codeTtlMs,\n    });\n  }\n  return Object.freeze({ outcome: \"rejected\", decidedAt });\n}\n","/**\n * EXPERIMENTAL PREVIEW — approve/reject saga keyed by the stable operation id.\n *\n * ```text\n * state and owner        the relay's authorization decision record. This saga\n *                        owns no decision state of its own and keeps nothing in\n *                        memory; it routes to `submitAuthorizationDecision`.\n * persisted evidence     one terminal decision row per request\n * resource occupied?     yes: the decision occupies its request, and the\n *                        one-time code and artifact are released exactly once\n * retry positively safe? yes for the saga call, because a repeated call never\n *                        decides again: it answers the stored outcome\n * transitions            undecided -> approved | rejected once, then replay-only\n * crash/reload           the outcome is durable before the caller sees it, so a\n *                        phone that never saw its response retries and is\n *                        answered from the store, on any process\n * cleanup owner          the relay transaction; nothing extra is allocated here\n * ```\n *\n * A second decide answers the *stored* outcome, not the resubmitted command: if\n * a rejected request is retried as approved, the answer is `rejected`. Compare\n * `outcome` against what you sent when that matters.\n *\n * The one-time code and encrypted artifact are released to the deciding call\n * only. A replay reports the outcome and no release material, because releasing\n * it twice is exactly what one-shot semantics forbid.\n *\n * @author taek <leekt216@gmail.com>\n */\n\nimport { type OwnerSigningArtifact, parseOwnerSigningArtifact } from \"@oaath/protocol\";\nimport type {\n  AuthorizationDecisionCommand,\n  SubmittedAuthorizationDecision,\n} from \"../authorization/decision.js\";\nimport { submitAuthorizationDecision } from \"../authorization/decision.js\";\nimport { fetchAuthorizationRequest } from \"../authorization/request.js\";\nimport { classifyStoredAuthorizationScope } from \"../authorization/scope.js\";\nimport { type RelayClock, relayNow } from \"../clock.js\";\nimport { OaathRelayError, relayFailure } from \"../relay/errors.js\";\nimport type { RelayCaller } from \"../security/authentication.js\";\nimport type { RelayKms } from \"../security/kms.js\";\nimport type { RelayStore } from \"../store/interface.js\";\nimport type { AuthorizationDecisionOutcome } from \"../store/records.js\";\nimport {\n  type OwnerPhonePermissionApprovals,\n  prepareOwnerPhonePermissionApproval,\n} from \"./permission-approval.js\";\n\nexport interface SubmitOwnerPhoneDecisionInput {\n  readonly store: RelayStore;\n  readonly clock: RelayClock;\n  readonly kms: RelayKms;\n  /** Authenticated `owner` caller; only the bound subject may decide. */\n  readonly caller: RelayCaller;\n  /** `operationId` from `projectOwnerPhoneRequest`. */\n  readonly operationId: string;\n  readonly command: AuthorizationDecisionCommand;\n  readonly codeTtlMs: number;\n  readonly permissionApprovals?: OwnerPhonePermissionApprovals;\n}\n\nexport interface OwnerPhoneDecision {\n  readonly operationId: string;\n  /** The stored outcome, which on a replay may differ from the command sent. */\n  readonly outcome: AuthorizationDecisionOutcome;\n  readonly decidedAt: number;\n  /** `decided` performed the transition; `replayed` answered the stored one. */\n  readonly settlement: \"decided\" | \"replayed\";\n  /** One-time release material, on the deciding call only. */\n  readonly release: SubmittedAuthorizationDecision | null;\n}\n\nexport async function submitOwnerPhoneDecision(\n  input: SubmitOwnerPhoneDecisionInput,\n): Promise<OwnerPhoneDecision> {\n  if (input.caller.role !== \"owner\") {\n    return relayFailure(\"relay_forbidden\", \"caller may not act in the required role\");\n  }\n  const pending = await fetchAuthorizationRequest({ ...input, requestId: input.operationId });\n  // A committed outcome wins before preparation, even if the provider is now unavailable.\n  if (pending.decision !== null)\n    return Object.freeze({\n      operationId: input.operationId,\n      outcome: pending.decision.outcome,\n      decidedAt: pending.decision.decidedAt,\n      settlement: \"replayed\",\n      release: null,\n    });\n  let command = input.command;\n  if (command.outcome === \"approved\" && !pending.expired) {\n    const scope = classifyStoredAuthorizationScope(pending.requestedScope, pending.requestId);\n    if (scope.kind === \"permission-request\") {\n      const prepared = await prepareOwnerPhonePermissionApproval(\n        input.permissionApprovals,\n        scope.request,\n      );\n      let artifact: Readonly<OwnerSigningArtifact>;\n      try {\n        artifact = parseOwnerSigningArtifact(JSON.parse(command.artifact));\n      } catch {\n        return relayFailure(\"relay_request_invalid\", \"phone signing artifact is invalid\");\n      }\n      command = {\n        outcome: \"approved\",\n        artifact: await prepared.complete(artifact, Math.floor(relayNow(input.clock) / 1000)),\n      };\n    }\n  }\n  try {\n    const release = await submitAuthorizationDecision({\n      store: input.store,\n      clock: input.clock,\n      kms: input.kms,\n      caller: input.caller,\n      requestId: input.operationId,\n      command,\n      codeTtlMs: input.codeTtlMs,\n    });\n    return Object.freeze({\n      operationId: input.operationId,\n      outcome: release.outcome,\n      decidedAt: release.decidedAt,\n      settlement: \"decided\",\n      release,\n    });\n  } catch (error) {\n    // Only \"already decided\" is idempotent. Ambiguous, expired, unauthorized,\n    // and unreadable stay failures: an unproven commit never becomes an answer.\n    if (!(error instanceof OaathRelayError) || error.code !== \"relay_already_decided\") throw error;\n  }\n  const state = await fetchAuthorizationRequest({\n    store: input.store,\n    clock: input.clock,\n    caller: input.caller,\n    requestId: input.operationId,\n  });\n  if (state.decision === null) {\n    return relayFailure(\"relay_internal\", \"decided request has no decision record\");\n  }\n  return Object.freeze({\n    operationId: input.operationId,\n    outcome: state.decision.outcome,\n    decidedAt: state.decision.decidedAt,\n    settlement: \"replayed\",\n    release: null,\n  });\n}\n","/**\n * Read-only owner inbox derived from retained relay requests and decisions.\n * No delivery state, lease or second queue is persisted. Recreating the service\n * reads the same pending requests; deciding or expiring one removes it from the\n * next listing. A summary is discovery only: consent/decision checks current state.\n */\nimport { type RelayClock, relayNow } from \"../clock.js\";\nimport { relayFailure } from \"../relay/errors.js\";\nimport type { RelayCaller } from \"../security/authentication.js\";\nimport { type RelayStore, withRelayTransaction } from \"../store/interface.js\";\nimport { ownerPhoneDisplayPayload } from \"./display.js\";\nimport type { OwnerPhonePushProjection } from \"./projection.js\";\n\nexport const OAATH_NATIVE_INBOX_VERSION = \"oaath.native-inbox/v1\" as const;\nconst INBOX_LIMIT = 20;\n\nexport interface OwnerPhoneInbox {\n  readonly version: typeof OAATH_NATIVE_INBOX_VERSION;\n  readonly requests: readonly Readonly<OwnerPhonePushProjection>[];\n}\n\n/** The store owns transaction resources; this read prepares, signs and submits nothing. */\nexport async function listOwnerPhoneRequests(input: {\n  readonly store: RelayStore;\n  readonly clock: RelayClock;\n  readonly caller: RelayCaller;\n}): Promise<Readonly<OwnerPhoneInbox>> {\n  if (input.caller.role !== \"owner\")\n    return relayFailure(\"relay_forbidden\", \"only an owner may read the inbox\");\n  const now = relayNow(input.clock);\n  const requests = await withRelayTransaction(input.store, (transaction) =>\n    transaction.listPendingOwnerRequests(input.caller.subject, now, INBOX_LIMIT),\n  );\n  if (requests.length > INBOX_LIMIT)\n    return relayFailure(\"relay_record_unreadable\", \"owner inbox is unbounded\");\n  return Object.freeze({\n    version: OAATH_NATIVE_INBOX_VERSION,\n    requests: Object.freeze(\n      await Promise.all(\n        requests.map(async (request) => {\n          if (request.ownerSubject !== input.caller.subject || request.expiresAt <= now) {\n            return relayFailure(\n              \"relay_record_unreadable\",\n              \"pending request does not match this owner inbox\",\n            );\n          }\n          return Object.freeze({\n            operationId: request.operationId,\n            expiresAt: request.expiresAt,\n            displayPayload: await ownerPhoneDisplayPayload(\n              request.ownerSubject,\n              request.operationId,\n            ),\n          });\n        }),\n      ),\n    ),\n  });\n}\n"],"mappings":"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"}