@seams/wallet-server 0.5.0

package/dist/types/wallet-server/src/router/cloudflare/d1/oidc/d1OidcBoundary.d.ts

@@ -0,0 +1,60 @@
+export type JsonWebKeyCache = {
+    readonly keysByKid: Map<string, JsonWebKey>;
+    readonly expiresAtMs: number;
+};
+export type JwtVerificationFailure = {
+    readonly ok: false;
+    readonly verified: false;
+    readonly code: string;
+    readonly message: string;
+};
+export type ParsedRs256Jwt = {
+    readonly headerB64u: string;
+    readonly payloadB64u: string;
+    readonly signatureB64u: string;
+    readonly payload: Record<string, unknown>;
+    readonly kid: string;
+};
+export type ParsedRs256JwtResult = {
+    readonly ok: true;
+    readonly jwt: ParsedRs256Jwt;
+} | JwtVerificationFailure;
+export type GoogleIdTokenClaims = {
+    readonly ok: true;
+    readonly sub: string;
+    readonly email?: string;
+    readonly name?: string;
+    readonly givenName?: string;
+    readonly familyName?: string;
+    readonly emailVerified?: boolean;
+    readonly hostedDomain?: string;
+};
+export type GoogleIdTokenClaimValidationResult = GoogleIdTokenClaims | JwtVerificationFailure;
+export declare function parseJwtAud(input: unknown): string[];
+export declare function parseCacheControlMaxAgeSec(input: unknown): number | null;
+export declare function parseGoogleJwks(input: unknown): Map<string, JsonWebKey> | null;
+export declare class CloudflareD1OidcJwksCache {
+    private googleJwksCache;
+    private googleJwksFetchPromise;
+    getGoogleJwks(): Promise<JsonWebKeyCache>;
+    private fetchGoogleJwks;
+}
+export declare function parseRs256JwtForVerification(input: {
+    readonly token: string;
+    readonly tokenLabel: string;
+}): ParsedRs256JwtResult;
+export declare function verifyRs256JwtSignature(input: {
+    readonly subtle: SubtleCrypto;
+    readonly jwt: ParsedRs256Jwt;
+    readonly jwk: JsonWebKey;
+    readonly tokenLabel: string;
+    readonly invalidSignatureMessage: string;
+}): Promise<{
+    readonly ok: true;
+} | JwtVerificationFailure>;
+export declare function parseBooleanJwtClaim(input: unknown): boolean | undefined;
+export declare function validateGoogleIdTokenClaims(input: {
+    readonly payload: Record<string, unknown>;
+    readonly clientId: string;
+}): GoogleIdTokenClaimValidationResult;
+//# sourceMappingURL=d1OidcBoundary.d.ts.map

package/dist/types/wallet-server/src/router/cloudflare/d1/oidc/d1OidcVerificationService.d.ts

@@ -0,0 +1,39 @@
+import type { IdentityStore, LinkIdentityResult } from '../../../../core/IdentityStore';
+import type { RouterApiIdentityService } from '../../../framework/authServicePort';
+import type { GithubOAuthConfig } from '../../../../core/types';
+type VerifyGoogleLoginInput = Parameters<RouterApiIdentityService['verifyGoogleLogin']>[0];
+type VerifyGoogleLoginResult = Awaited<ReturnType<RouterApiIdentityService['verifyGoogleLogin']>>;
+type GoogleOidcPublicConfig = ReturnType<RouterApiIdentityService['getGoogleOidcPublicConfig']>;
+type GithubOAuthPublicConfig = ReturnType<RouterApiIdentityService['getGithubOAuthPublicConfig']>;
+type OidcIdentityLinker = (input: {
+    readonly userId: string;
+    readonly subject: string;
+    readonly allowMoveIfSoleIdentity?: boolean;
+}) => Promise<LinkIdentityResult>;
+export declare class CloudflareD1OidcVerificationService {
+    private readonly googleOidcClientId;
+    private readonly githubOAuth;
+    private readonly identityStore;
+    private readonly linkIdentity;
+    private readonly oidcJwksCache;
+    constructor(input: {
+        readonly googleOidcClientId: string | undefined;
+        readonly githubOAuth: GithubOAuthConfig | undefined;
+        readonly identityStore: IdentityStore;
+        readonly linkIdentity: OidcIdentityLinker;
+    });
+    getGoogleOidcPublicConfig(): GoogleOidcPublicConfig;
+    getGithubOAuthPublicConfig(): GithubOAuthPublicConfig;
+    verifyGithubOAuthCode(input: Parameters<RouterApiIdentityService['verifyGithubOAuthCode']>[0]): Promise<Awaited<ReturnType<RouterApiIdentityService['verifyGithubOAuthCode']>>>;
+    verifyGoogleLogin(input: VerifyGoogleLoginInput): Promise<VerifyGoogleLoginResult>;
+    /**
+     * Recovery verifies a Google credential before an Email enrollment exists.
+     * It must not create or relink a generic identity as a side effect of that
+     * factor check; the recovery finalizer owns the eventual enrollment link.
+     */
+    verifyGoogleLoginForRecovery(input: VerifyGoogleLoginInput): Promise<VerifyGoogleLoginResult>;
+    private verifyGoogleIdToken;
+    private linkGoogleIdentity;
+}
+export {};
+//# sourceMappingURL=d1OidcVerificationService.d.ts.map

package/dist/types/wallet-server/src/router/cloudflare/d1/passkeyCustody/d1PasskeyCustodyEnvelopeStore.d.ts

@@ -0,0 +1,335 @@
+import { type PasskeyDeviceEnvelopeIndexRecord, type PasskeyCustodyEnvelopeRecord, type WalletCustodyEnvelopeOwnership } from '../../../../../../shared-ts/src/passkey-custody';
+import { type WalletCredentialActivityRecordV1 } from '../../../../../../shared-ts/src/passkey-custody/credentialActivity';
+import type { PasskeyEnvelopeId, WalletId, WebAuthnCredentialIdB64u, WebAuthnRpId, WalletAuthMethodId } from '../../../../../../shared-ts/src/utils/domainIds';
+import type { D1DatabaseLike, D1PreparedStatementLike } from '../../../../storage/tenantRoute';
+import { type CloudflareD1VersionedJsonRecordScopeV1 } from '../versionedJson/d1VersionedJsonRecordStore';
+/**
+ * Opaque custody storage for factor-sealed custody envelopes.
+ *
+ * The store validates credential, wallet, lifecycle, revision, and digest
+ * facts, and it cannot open an envelope or report its plaintext as live: the
+ * KEK only ever exists inside the browser's secure worker. Ciphertext lives
+ * here because a browser with empty IndexedDB must be able to retrieve it after
+ * an exact WebAuthn assertion — a browser-only record is never the cross-device
+ * source of truth.
+ *
+ * Persistence rides on the shared versioned JSON record store, so CAS, batching,
+ * and tenant scoping behave exactly as they do for every other Gateway D1
+ * record. Two version identities are deliberately distinct:
+ *
+ * - the store's opaque `version` string is the transport CAS token;
+ * - the domain `envelopeRevision` increments by exactly 1 per rewrap and is
+ *   bound into the envelope's AAD, so an old ciphertext cannot be replayed into
+ *   a newer revision.
+ *
+ * A lifecycle transition changes no ciphertext and therefore never bumps
+ * `envelopeRevision`.
+ */
+export declare const PASSKEY_ENVELOPE_KEY_PREFIX = "passkey-envelope";
+export type CloudflareD1PasskeyCustodyEnvelopeStoreOptions = {
+    readonly database: D1DatabaseLike;
+    readonly scope: CloudflareD1VersionedJsonRecordScopeV1;
+};
+/**
+ * Identifies the enrolled factor an envelope belongs to.
+ *
+ * Factors are interchangeable unwrap paths to the same custody seed, so an
+ * envelope is addressed by factor rather than by credential alone — otherwise
+ * an Email OTP envelope would have no address at all.
+ */
+export type WalletCustodyFactorRef = {
+    readonly kind: 'passkey';
+    readonly rpId: WebAuthnRpId;
+    readonly credentialIdB64u: WebAuthnCredentialIdB64u;
+} | {
+    readonly kind: 'email_otp';
+    readonly enrollmentId: string;
+    readonly enrollmentSealKeyVersion: string;
+};
+export type PasskeyCustodyEnvelopeLocator = {
+    readonly walletId: WalletId;
+    readonly factor: WalletCustodyFactorRef;
+    readonly envelopeId: PasskeyEnvelopeId;
+};
+/** The factor address a stored envelope actually carries. */
+export declare function envelopeFactorRef(envelope: PasskeyCustodyEnvelopeRecord): WalletCustodyFactorRef;
+/**
+ * Every terminal outcome of an authenticated envelope lookup. Each non-active
+ * branch is an explicit failure the caller must handle: none of them may fall
+ * back to deriving a fresh custody root.
+ */
+export type PasskeyCustodyEnvelopeLookupResult = {
+    readonly kind: 'active';
+    readonly envelope: PasskeyCustodyEnvelopeRecord;
+    /** CAS token for a follow-up rewrap or lifecycle transition. */
+    readonly storeVersion: string;
+} | {
+    readonly kind: 'retired';
+    readonly envelopeId: PasskeyEnvelopeId;
+    readonly retiredAtMs: number;
+} | {
+    readonly kind: 'revoked';
+    readonly envelopeId: PasskeyEnvelopeId;
+    readonly revokedAtMs: number;
+} | {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'digest_mismatch';
+    readonly envelopeId: PasskeyEnvelopeId;
+    readonly storedCiphertextDigestB64u: string;
+    readonly actualCiphertextDigestB64u: string;
+};
+export type PasskeyCustodyEnvelopeFactorLookupResult = PasskeyCustodyEnvelopeLookupResult | {
+    readonly kind: 'conflict';
+};
+/**
+ * Whether a browser's cached ciphertext may still be used. A cache is usable
+ * only at the exact server revision and digest; anything else must be refetched.
+ */
+export type PasskeyCustodyEnvelopeCacheValidation = {
+    readonly kind: 'cache_valid';
+    readonly envelope: PasskeyCustodyEnvelopeRecord;
+} | {
+    readonly kind: 'cache_stale';
+    readonly serverRevision: number;
+    readonly serverCiphertextDigestB64u: string;
+} | {
+    readonly kind: 'cache_unusable';
+    readonly lookup: PasskeyCustodyEnvelopeLookupResult;
+};
+export type PasskeyCustodyEnvelopePutResult = {
+    readonly kind: 'stored';
+    readonly storeVersion: string;
+    readonly envelopeRevision: number;
+} | {
+    readonly kind: 'version_mismatch';
+} | {
+    readonly kind: 'revision_conflict';
+    readonly expectedRevision: number;
+} | {
+    readonly kind: 'not_found';
+} | {
+    readonly kind: 'terminal_lifecycle';
+    readonly state: 'revoked';
+};
+/** What the caller believes it is replacing, checked before the ciphertext moves. */
+export type ExpectedCustodyEnvelopeState = {
+    readonly envelopeId: PasskeyEnvelopeId;
+    readonly envelopeRevision: number;
+    readonly ownership: WalletCustodyEnvelopeOwnership;
+};
+export type PasskeyCustodyEnvelopeRewrapResult = PasskeyCustodyEnvelopePutResult | {
+    readonly kind: 'ownership_conflict';
+    readonly reason: string;
+};
+export type PasskeyCustodyEnvelopeRevocationResult = {
+    readonly kind: 'stored';
+    readonly revokedEnvelopeIds: readonly PasskeyEnvelopeId[];
+} | {
+    readonly kind: 'refused';
+    readonly reason: string;
+} | {
+    readonly kind: 'version_mismatch';
+};
+export type PasskeyCustodyEnvelopeLinkResult = {
+    readonly kind: 'stored';
+    readonly storeVersion: string;
+} | {
+    readonly kind: 'version_mismatch';
+} | {
+    readonly kind: 'conflict';
+};
+export type PasskeyFactorWithoutCustodyLinkResult = {
+    readonly kind: 'stored';
+} | {
+    readonly kind: 'conflict';
+};
+export type WalletCredentialActivityProjection = {
+    readonly index: PasskeyDeviceEnvelopeIndexRecord;
+    readonly activity: WalletCredentialActivityRecordV1;
+};
+export type WalletCredentialActivityMutationResult = {
+    readonly kind: 'updated';
+    readonly projection: WalletCredentialActivityProjection;
+} | {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'conflict';
+} | {
+    readonly kind: 'invalid_label';
+    readonly reason: string;
+};
+/**
+ * The record key for one envelope, exported so the registration commit path
+ * addresses envelopes with this exact definition rather than a copy of it. A
+ * second spelling of this key would write rows no lookup could ever find.
+ *
+ * Envelopes are addressed by wallet, factor, and envelope id together, so a
+ * lookup can never return an envelope belonging to another factor even if the
+ * envelope id were guessed. JSON-encoded so no delimiter inside an id can
+ * splice one locator into another: enrollment ids are caller strings and
+ * domain ids permit ':'. A joined string would let
+ * {enrollment "e", envelope "x:y"} collide with {enrollment "e:x", envelope "y"}.
+ */
+export declare function passkeyCustodyEnvelopeRecordKey(locator: PasskeyCustodyEnvelopeLocator): string;
+/** The factor address a stored envelope carries, for callers building locators. */
+export declare function passkeyCustodyEnvelopeLocatorOf(envelope: PasskeyCustodyEnvelopeRecord): PasskeyCustodyEnvelopeLocator;
+export declare class CloudflareD1PasskeyCustodyEnvelopeStore {
+    private readonly records;
+    private readonly activityRecords;
+    private readonly database;
+    private readonly scope;
+    constructor(options: CloudflareD1PasskeyCustodyEnvelopeStoreOptions);
+    private recordKey;
+    /**
+     * Reads one envelope and classifies it. The caller must have already verified
+     * a WebAuthn assertion for this exact wallet, RP, credential, and challenge —
+     * this store authenticates nothing on its own.
+     */
+    lookupEnvelope(locator: PasskeyCustodyEnvelopeLocator): Promise<PasskeyCustodyEnvelopeLookupResult>;
+    /**
+     * Confirms a browser cache entry against the active server envelope. A cache
+     * hit requires the exact revision and ciphertext digest, so a cache that
+     * drifted across a rewrap is refetched rather than opened.
+     */
+    validateCachedEnvelope(args: {
+        readonly locator: PasskeyCustodyEnvelopeLocator;
+        readonly cachedRevision: number;
+        readonly cachedCiphertextDigestB64u: string;
+    }): Promise<PasskeyCustodyEnvelopeCacheValidation>;
+    /**
+     * Stores the first revision of a new envelope. Fails with `version_mismatch`
+     * if any envelope already exists at this locator.
+     */
+    /**
+     * Every envelope stored for one wallet, in key order.
+     *
+     * Credential management needs this and cannot be written without it: whether
+     * removing a passkey is safe depends on whether *another* active envelope
+     * still protects the same custody seed, and that question is unanswerable
+     * from a single locator.
+     *
+     * The scan is bounded by the wallet's own key prefix, so it cannot reach
+     * another wallet's rows even if a caller passes a crafted id — the prefix is
+     * a JSON-encoded array whose first element is the wallet.
+     */
+    listWalletEnvelopes(walletId: WalletId, options?: {
+        readonly limit?: number;
+    }): Promise<readonly PasskeyCustodyEnvelopeRecord[]>;
+    /**
+     * Revocation statements for every live envelope sealed under one factor,
+     * for a caller whose transaction is owned elsewhere.
+     *
+     * Auth-method revocation is that caller: the method, its sessions, and its
+     * sealed envelope have to become unusable together, and the authority store
+     * owns that batch. Returning statements rather than running them is what
+     * keeps this from becoming a second, non-atomic revocation path.
+     *
+     * The last-active-envelope guard rides along, so revoking the final factor
+     * that can open the wallet custody seed still aborts.
+     */
+    prepareMethodEnvelopeRevocationStatements(input: {
+        readonly walletId: WalletId;
+        readonly walletAuthMethodId: WalletAuthMethodId;
+        readonly revokedAtMs: number;
+    }): Promise<{
+        readonly kind: 'prepared';
+        readonly statements: readonly D1PreparedStatementLike[];
+    } | {
+        readonly kind: 'refused';
+        readonly reason: string;
+    } | {
+        readonly kind: 'version_mismatch';
+    }>;
+    private prepareEnvelopeRevocationStatements;
+    /** Returns the public credential-management view; activity never enters envelope AAD. */
+    listWalletCredentialActivity(walletId: WalletId): Promise<readonly WalletCredentialActivityProjection[]>;
+    renameWalletCredential(input: {
+        readonly walletId: WalletId;
+        readonly envelopeId: PasskeyEnvelopeId;
+        readonly label?: string;
+        readonly nowMs: number;
+    }): Promise<WalletCredentialActivityMutationResult>;
+    /** Called only after a passkey assertion has successfully opened custody. */
+    recordWalletCredentialUse(input: {
+        readonly walletId: WalletId;
+        readonly envelopeId: PasskeyEnvelopeId;
+        readonly usedAtMs: number;
+    }): Promise<WalletCredentialActivityMutationResult>;
+    private findPasskeyEnvelope;
+    private readActivity;
+    private mutateActivity;
+    private prepareRemainingActiveEnvelopeGuard;
+    lookupEnvelopeForFactor(input: {
+        readonly walletId: WalletId;
+        readonly factor: WalletCustodyFactorRef;
+    }): Promise<PasskeyCustodyEnvelopeFactorLookupResult>;
+    lookupEnvelopeForWalletAuthMethod(input: {
+        readonly walletId: WalletId;
+        readonly factor: WalletCustodyFactorRef;
+        readonly walletAuthMethodId: WalletAuthMethodId;
+    }): Promise<PasskeyCustodyEnvelopeFactorLookupResult>;
+    createEnvelope(envelope: PasskeyCustodyEnvelopeRecord): Promise<PasskeyCustodyEnvelopePutResult>;
+    /**
+     * Inserts a new custody envelope together with caller-owned authenticator,
+     * credential-binding, and wallet-auth-method statements in one D1 batch.
+     * The envelope row is insert-only, so a repeated envelope identity or any
+     * conflicting credential aborts the complete transaction.
+     *
+     * The factor kind is the caller's to assert, not this store's. Refactor 109C
+     * enrols an Email OTP factor by exactly this route — a new envelope holding
+     * the same seed, committed with the auth-method insert — and each branch has
+     * already verified the factor it built the envelope for by the time it gets
+     * here. A kind check here would only re-state one branch's assumption and
+     * refuse the other.
+     */
+    linkWalletCustodyFactorAtomically(input: {
+        readonly envelope: PasskeyCustodyEnvelopeRecord;
+        readonly additionalStatements: readonly D1PreparedStatementLike[];
+    }): Promise<PasskeyCustodyEnvelopeLinkResult>;
+    /**
+     * Commits a linked-device owner credential without inserting a generic
+     * wallet-custody envelope. The linked Device 2 root is a local export
+     * repository record and never belongs in this seed store.
+     */
+    commitPasskeyFactorWithoutCustodyAtomically(input: {
+        readonly additionalStatements: readonly D1PreparedStatementLike[];
+    }): Promise<PasskeyFactorWithoutCustodyLinkResult>;
+    /**
+     * Replaces an envelope's ciphertext at exactly the next revision.
+     *
+     * The read-then-CAS window is closed by the store version: a concurrent
+     * writer changes it, so the put fails rather than skipping a revision.
+     *
+     * `expected` is the caller's statement of which row it believes it is
+     * replacing — the exact envelope, the exact revision it was read at, and the
+     * exact method that owned it. The store refuses when any of the three has
+     * moved. Passing the replacement alone would let a caller that read a stale
+     * row overwrite whatever is there now as long as the arithmetic happened to
+     * line up, and for an envelope the arithmetic is not the identity.
+     */
+    rewrapEnvelope(envelope: PasskeyCustodyEnvelopeRecord, expected: ExpectedCustodyEnvelopeState): Promise<PasskeyCustodyEnvelopeRewrapResult>;
+    /**
+     * Marks an active envelope superseded. Retired rows stay readable so a
+     * lookup can report `retired` explicitly instead of `missing`.
+     */
+    retireEnvelope(args: {
+        readonly locator: PasskeyCustodyEnvelopeLocator;
+        readonly retiredAtMs: number;
+    }): Promise<PasskeyCustodyEnvelopePutResult>;
+    /**
+     * Revokes an envelope terminally. The row is retained as a credential
+     * tombstone — credential replacement needs the prior credential's record —
+     * but it is excluded from every active retrieval.
+     */
+    revokeEnvelope(args: {
+        readonly locator: PasskeyCustodyEnvelopeLocator;
+        readonly revokedAtMs: number;
+    }): Promise<PasskeyCustodyEnvelopePutResult>;
+    /**
+     * Lifecycle transitions never touch ciphertext, so `envelopeRevision` is
+     * carried forward unchanged and the sealed AAD stays valid.
+     */
+    private transitionLifecycle;
+}
+//# sourceMappingURL=d1PasskeyCustodyEnvelopeStore.d.ts.map