@seams/wallet-server 0.28.0 → 0.30.0

package/dist/esm/router/transport/fetch/walletOwnerOperationAuthorization.js

@@ -0,0 +1,306 @@
+import { parseEmailOtpChallengeId, parseOrgId, parseProviderSubject, parseWalletId, parseWebAuthnCredentialIdB64u } from "../../../shared-ts/src/utils/domainIds.js";
+import { normalizeOptionalTrimmedString } from "../../../shared-ts/src/utils/normalize.js";
+import { alphabetizeStringify } from "../../../shared-ts/src/utils/digests.js";
+import { sha256Utf8DigestB64u } from "../../../shared-ts/src/utils/canonicalPrimitives.js";
+import { requireParsed } from "../../../shared-ts/src/passkey-custody/primitives.js";
+import { computeWalletOwnerAdminChallengeDigest } from "../../../shared-ts/src/authorization/walletOwnerOperation.js";
+import { buildVaultOperationRef, parseAuthFactorId, parseAuthorizationAuditEventId, parseAuthorizationEvidenceId, parseAuthorizationEvidenceSetId, parseAuthorizedOperationId, parseCapabilityId, parseCapabilityOperationId, parsePrincipalId, parseTenantId } from "../../../shared-ts/src/authorization/capabilityKinds.js";
+import { buildDelegatedWalletAuthorityV1, buildFullOwnerPermissionsV1, sameDelegatedWalletAuthorityV1 } from "../../../shared-ts/src/authorization/delegatedAuthority.js";
+import { buildCapabilityOperationEnvelope, computeCapabilityOperationFingerprintDigest } from "../../../shared-ts/src/authorization/operationFingerprint.js";
+import { buildPasskeyWalletAuthAuthority, walletAuthAuthorityRef } from "../../../shared-ts/src/utils/walletAuthAuthority.js";
+import { parseSessionOrigin, parseVerifiedOwnerProofId } from "../../../authorization/domain.js";
+import { buildVerifiedWalletOperationEmailOtpFactorResult, buildVerifiedWalletOperationPasskeyFactorResult } from "../../../authorization/factorEvidence.js";
+import { EMAIL_OTP_CHANNEL, WALLET_EMAIL_OTP_UNLOCK_OPERATION } from "../../../shared-ts/src/utils/emailOtpDomain.js";
+import { parseWebAuthnAuthenticationCredential } from "../../auth/webAuthnCredentialCodecs.js";
+import { emailOtpStatusCode, hashEmailOtpOperationBinding } from "../../domains/emailOtp/emailOtpSessionRouteHelpers.js";
+import { toFetchRouteResponse } from "../../framework/routeResponses.js";
+import { parseCustodyOwnerProof } from "./routes/walletCustodyRequestBoundary.js";
+//#region src/router/transport/fetch/walletOwnerOperationAuthorization.ts
+const CUSTODY_OPERATION_CAPABILITY_ID = "wallet-custody-admin";
+const CUSTODY_PROOF_TTL_MS = 6e4;
+function walletOwnerOperationAuthorizationId(operation, challenge) {
+	return requireParsed(parseAuthorizedOperationId(`wallet-custody:authorized:wallet-custody:${operation}:${challenge}`), "owner operation");
+}
+function hasFullOwnerAuthority(authority) {
+	return sameDelegatedWalletAuthorityV1(buildDelegatedWalletAuthorityV1({ permissions: authority.permissions }), buildDelegatedWalletAuthorityV1({ permissions: buildFullOwnerPermissionsV1() }));
+}
+async function custodyDigest(domain, value) {
+	return sha256Utf8DigestB64u(`${domain}|${alphabetizeStringify(value)}`);
+}
+async function buildWalletCustodyOperation(input) {
+	const tenantId = requireParsed(parseTenantId(input.tenantId), "authorization");
+	const principalId = requireParsed(parsePrincipalId(input.principalId), "authorization");
+	const capabilityId = requireParsed(parseCapabilityId(CUSTODY_OPERATION_CAPABILITY_ID), "authorization");
+	const operationRef = buildVaultOperationRef("vault.reveal");
+	const laneDigest = await custodyDigest("seams:wallet-custody:lane:v1", {
+		capabilityId,
+		operation: input.operation,
+		operationRef
+	});
+	const challengeDigest = await computeWalletOwnerAdminChallengeDigest({
+		walletId: input.walletId,
+		operation: input.operation,
+		payload: input.payload,
+		requestOrigin: input.requestOrigin
+	});
+	const intentDigest = challengeDigest;
+	const displayDigest = await custodyDigest("seams:wallet-custody:display:v1", {
+		walletId: input.walletId,
+		operation: input.operation
+	});
+	return {
+		operation: buildCapabilityOperationEnvelope({
+			tenantId,
+			principalId,
+			capabilityId,
+			operationId: requireParsed(parseCapabilityOperationId(`wallet-custody:${input.operation}:${intentDigest}`), "authorization"),
+			operation: operationRef,
+			digests: {
+				laneDigest,
+				intentDigest,
+				displayDigest
+			}
+		}),
+		challengeDigest
+	};
+}
+async function authorizeWalletOwnerOperation(input) {
+	const requestOrigin = normalizeOptionalTrimmedString(input.ctx.request.headers.get("origin"));
+	if (!requestOrigin) return toCustodyAuthorizationFailure(400, "invalid_origin", "request Origin is required");
+	let origin;
+	let proof;
+	let walletId;
+	try {
+		origin = parseSessionOrigin(requestOrigin);
+		walletId = requireParsed(parseWalletId(input.walletId), "authorization");
+		proof = parseCustodyOwnerProof(input.factorProof);
+	} catch (error) {
+		return toCustodyAuthorizationFailure(400, "invalid_owner_proof", error instanceof Error ? error.message : "owner proof is invalid");
+	}
+	if (proof.kind === "passkey" && proof.walletId !== input.walletId) return toCustodyAuthorizationFailure(403, "scope_mismatch", "owner proof wallet differs");
+	let principalId;
+	let factor;
+	let ownerAuthorityRef;
+	let ownerAuthority;
+	let operation;
+	let challengeDigest;
+	try {
+		principalId = proof.kind === "passkey" ? input.walletId : proof.provider_subject_id;
+		const built = await buildWalletCustodyOperation({
+			tenantId: input.ctx.service.authorizedOperations.tenantId,
+			principalId,
+			walletId: input.walletId,
+			operation: input.operation,
+			payload: input.payload,
+			requestOrigin
+		});
+		operation = built.operation;
+		challengeDigest = built.challengeDigest;
+	} catch (error) {
+		return toCustodyAuthorizationFailure(400, "invalid_owner_proof", error instanceof Error ? error.message : "owner proof binding is invalid");
+	}
+	const operationFingerprintDigest = await computeCapabilityOperationFingerprintDigest(operation);
+	const nowMs = Date.now();
+	if (proof.challenge_digest !== String(challengeDigest)) return toCustodyAuthorizationFailure(403, "scope_mismatch", "factor proof challenge does not match the requested operation");
+	if (proof.kind === "passkey") {
+		let authority;
+		try {
+			authority = buildPasskeyWalletAuthAuthority({
+				walletId,
+				rpId: proof.rpId,
+				credentialIdB64u: proof.credentialIdB64u
+			});
+		} catch (error) {
+			return toCustodyAuthorizationFailure(400, "invalid_owner_proof", error instanceof Error ? error.message : "passkey authority is invalid");
+		}
+		const active = await input.ctx.service.walletAuthMethods.resolveActivePasskeyAuthorityForVerifiedCredential({
+			walletId,
+			rpId: authority.verifier.rpId,
+			credentialIdB64u: authority.factor.credentialIdB64u
+		});
+		if (!active.ok) return toCustodyAuthorizationFailure(403, active.code, active.message);
+		if (!hasFullOwnerAuthority(active.walletAuthority)) return toCustodyAuthorizationFailure(403, "forbidden", "Full owner authority is required");
+		ownerAuthority = active.walletAuthority;
+		const credential = parseWebAuthnAuthenticationCredential(proof.webauthn_authentication);
+		if (!credential) return toCustodyAuthorizationFailure(400, "invalid_owner_proof", "passkey assertion is invalid");
+		if (String(credential.rawId || credential.id).trim() !== authority.factor.credentialIdB64u) return toCustodyAuthorizationFailure(401, "unauthorized", "passkey credential changed");
+		const verified = await input.ctx.service.webAuthn.verifyWebAuthnAuthenticationLite({
+			userId: input.walletId,
+			rpId: authority.verifier.rpId,
+			expectedChallenge: challengeDigest,
+			expected_origin: requestOrigin,
+			webauthn_authentication: credential
+		});
+		if (!verified.success || !verified.verified) return toCustodyAuthorizationFailure(401, verified.code || "not_verified", verified.message || "WebAuthn authentication verification failed");
+		ownerAuthorityRef = await walletAuthAuthorityRef({ authority: active.authority });
+		factor = buildVerifiedWalletOperationPasskeyFactorResult({
+			tenantId: operation.tenantId,
+			principalId: operation.principalId,
+			walletId,
+			authorityRef: ownerAuthorityRef,
+			requestOrigin: origin,
+			audience: origin,
+			factorId: requireParsed(parseAuthFactorId(`passkey:${authority.factor.credentialIdB64u}`), "authorization"),
+			credentialIdB64u: requireParsed(parseWebAuthnCredentialIdB64u(authority.factor.credentialIdB64u), "authorization"),
+			assertionDigest: await custodyDigest("seams:wallet-custody:assertion:v1", { credential }),
+			operation,
+			verifiedAtMs: nowMs,
+			expiresAtMs: nowMs + CUSTODY_PROOF_TTL_MS
+		});
+	} else {
+		const providerSubject = requireParsed(parseProviderSubject(proof.provider_subject_id), "authorization");
+		const orgId = requireParsed(parseOrgId(input.ctx.service.authorizedOperations.tenantId), "authorization");
+		const active = await input.ctx.service.walletAuthMethods.resolveActiveEmailOtpAuthorityForVerifiedSubject({
+			walletId: input.walletId,
+			providerUserId: proof.provider_subject_id
+		});
+		if (!active.ok) return toCustodyAuthorizationFailure(403, active.code, active.message);
+		const activeAuthorityRef = await walletAuthAuthorityRef({ authority: active.authority });
+		ownerAuthorityRef = activeAuthorityRef;
+		ownerAuthority = active.walletAuthority;
+		const ownerProofBindingDigest = await hashEmailOtpOperationBinding({
+			walletId: input.walletId,
+			providerUserId: proof.provider_subject_id,
+			orgId,
+			operation: `wallet_custody:${input.operation}`,
+			requestOrigin,
+			audience: requestOrigin,
+			authorityRef: activeAuthorityRef,
+			operationFingerprintDigest: challengeDigest
+		});
+		const verified = await input.ctx.service.emailOtp.verifyEmailOtpChallenge({
+			userId: proof.provider_subject_id,
+			walletId: input.walletId,
+			orgId,
+			challengeId: proof.challenge_id,
+			otpCode: proof.otp_code,
+			otpChannel: EMAIL_OTP_CHANNEL,
+			ownerProofBindingDigest,
+			operation: WALLET_EMAIL_OTP_UNLOCK_OPERATION
+		});
+		if (!verified.ok) return toCustodyAuthorizationFailure(verified.code === "invalid_body" ? 400 : 401, verified.code, verified.message);
+		const consumed = await input.ctx.service.emailOtp.consumeEmailOtpGrant({
+			subject: {
+				kind: "provider_identity",
+				orgId,
+				providerSubject,
+				walletId
+			},
+			loginGrant: verified.loginGrant,
+			otpChannel: EMAIL_OTP_CHANNEL
+		});
+		if (!consumed.ok) return toCustodyAuthorizationFailure(emailOtpStatusCode(consumed.code), consumed.code, consumed.message);
+		factor = buildVerifiedWalletOperationEmailOtpFactorResult({
+			tenantId: operation.tenantId,
+			principalId: operation.principalId,
+			walletId,
+			authorityRef: activeAuthorityRef,
+			requestOrigin: origin,
+			audience: origin,
+			factorId: requireParsed(parseAuthFactorId(`email_otp:${active.authority.factor.provider}:${proof.provider_subject_id}`), "authorization"),
+			operation,
+			challengeId: requireParsed(parseEmailOtpChallengeId(consumed.challengeId), "authorization"),
+			verificationReceiptDigest: await custodyDigest("seams:wallet-custody:otp-receipt:v1", {
+				challengeId: consumed.challengeId,
+				operationFingerprintDigest
+			}),
+			verifiedAtMs: nowMs,
+			expiresAtMs: Math.min(nowMs + CUSTODY_PROOF_TTL_MS, verified.grantExpiresAtMs)
+		});
+	}
+	const ownerProof = await input.ctx.service.authorizedOperations.buildVerifiedOwnerProof({
+		purpose: "operation",
+		proofId: parseVerifiedOwnerProofId(`wallet-custody:${operation.operationId}`),
+		factor
+	});
+	if (ownerProof.purpose !== "operation" || ownerProof.operation.operationFingerprintDigest !== operationFingerprintDigest) return toCustodyAuthorizationFailure(403, "owner_proof_rejected", "owner proof binding is invalid");
+	const existing = await input.ctx.service.authorizedOperations.readAuthorizedOperation({
+		tenantId: operation.tenantId,
+		operationFingerprintDigest
+	});
+	if (existing) {
+		if (existing.authorization.kind !== "verified_step_up" || existing.quota.kind !== "quota_neutral") return toCustodyAuthorizationFailure(403, "owner_proof_rejected", "Owner operation authorization differs");
+		return {
+			ok: false,
+			response: authorizedOperationReplay(existing)
+		};
+	}
+	const evidenceSet = await input.ctx.service.authorizedOperations.recordVerifiedWalletOperationFactorEvidenceSet({
+		operation,
+		evidenceId: requireParsed(parseAuthorizationEvidenceId(`wallet-custody:evidence:${operation.operationId}`), "authorization"),
+		evidenceSetId: requireParsed(parseAuthorizationEvidenceSetId(`wallet-custody:evidence-set:${operation.operationId}`), "authorization"),
+		factor
+	});
+	const admission = await input.ctx.service.authorizedOperations.admitAuthorizedOperation({ operation: {
+		tenantId: operation.tenantId,
+		authorizedOperationId: walletOwnerOperationAuthorizationId(input.operation, challengeDigest),
+		auditEventId: requireParsed(parseAuthorizationAuditEventId(`wallet-custody:audit:${operation.operationId}`), "authorization"),
+		operation,
+		authorization: {
+			kind: "verified_step_up",
+			evidenceSetDigest: evidenceSet.evidenceSetDigest
+		},
+		quota: { kind: "quota_neutral" },
+		claimedAtMs: nowMs
+	} });
+	switch (admission.kind) {
+		case "claimed": return {
+			ok: true,
+			operation: admission.operation,
+			ownerAuthority
+		};
+		case "replayed":
+		case "operation_in_progress": return {
+			ok: false,
+			response: authorizedOperationReplay(admission.operation)
+		};
+		case "authorization_grant_rejected":
+		case "verified_step_up_rejected":
+		case "wallet_session_quota_exhausted":
+		case "material_mismatch": return toCustodyAuthorizationFailure(403, "owner_proof_rejected", "owner proof was rejected");
+	}
+}
+function toCustodyAuthorizationFailure(status, code, message) {
+	return {
+		ok: false,
+		response: routeErrorResponse(status, code, message)
+	};
+}
+function routeErrorResponse(status, code, message) {
+	return toFetchRouteResponse({
+		status,
+		body: {
+			ok: false,
+			code,
+			message
+		}
+	});
+}
+function authorizedOperationReplay(operation) {
+	if (operation.lifecycle !== "completed") return routeErrorResponse(409, "recovery_in_progress", "wallet recovery is still in progress");
+	return new Response(operation.response.bodyText, {
+		status: operation.response.status,
+		headers: { "content-type": operation.response.contentType }
+	});
+}
+async function completeWalletOwnerOperation(ctx, operation, status, body, result = "succeeded") {
+	const bodyText = JSON.stringify(body);
+	await ctx.service.authorizedOperations.completeAuthorizedOperation({
+		operation,
+		result,
+		response: {
+			status,
+			contentType: "application/json",
+			bodyText
+		},
+		completedAtMs: Date.now()
+	});
+	return toFetchRouteResponse({
+		status,
+		body
+	});
+}
+//#endregion
+export { authorizeWalletOwnerOperation, completeWalletOwnerOperation, walletOwnerOperationAuthorizationId };
+
+//# sourceMappingURL=walletOwnerOperationAuthorization.js.map

package/dist/esm/shared-ts/src/auth/externalAuth.js

@@ -1,33 +1,106 @@
 import { parseWalletId } from "../utils/domainIds.js";
 import { requireCanonicalString, requireRecord } from "../utils/validation.js";
-import { parseUnixMs } from "../passkey-custody/primitives.js";
+import { parseEd25519PublicKeyB64u, parseUnixMs } from "../passkey-custody/primitives.js";
 //#region ../shared-ts/src/auth/externalAuth.ts
 const EXTERNAL_AUTH_PATH = "/wallet/external-auth";
+function parseExternalAuthProvider(raw) {
+	const value = requireRecord(raw, "external authentication provider");
+	switch (value.kind) {
+		case "disabled": return { kind: "disabled" };
+		case "google": return {
+			kind: "google",
+			clientId: requireCanonicalString(value.clientId, "clientId")
+		};
+		case "application": {
+			const issuer = requireCanonicalString(value.issuer, "issuer");
+			const url = new URL(issuer);
+			if (url.protocol !== "https:" || url.origin !== issuer) throw new Error("Application issuer must be a canonical HTTPS origin");
+			return {
+				kind: "application",
+				issuer,
+				publicKeyB64u: parseEd25519PublicKeyB64u(value.publicKeyB64u, "publicKeyB64u")
+			};
+		}
+		default: throw new Error("Unsupported external authentication provider");
+	}
+}
+function externalAuthConfiguration(provider, revision) {
+	switch (provider.kind) {
+		case "disabled": return {
+			kind: "disabled",
+			revision
+		};
+		case "google": return {
+			kind: "google",
+			revision,
+			clientId: provider.clientId
+		};
+		case "application": return {
+			kind: "application",
+			revision,
+			issuer: provider.issuer,
+			publicKeyB64u: provider.publicKeyB64u
+		};
+		default: return assertNever(provider);
+	}
+}
 function parseExternalAuthConfiguration(raw) {
 	const value = requireRecord(raw, "external authentication configuration");
 	if (typeof value.revision !== "number" || !Number.isSafeInteger(value.revision) || value.revision < 0) throw new Error("Invalid external authentication revision");
-	if (value.kind === "disabled") return {
-		kind: "disabled",
-		revision: value.revision
-	};
-	if (value.kind === "google") return {
-		kind: "google",
-		revision: value.revision,
-		clientId: requireCanonicalString(value.clientId, "clientId")
-	};
-	throw new Error("Unsupported external authentication configuration");
+	return externalAuthConfiguration(parseExternalAuthProvider(value), value.revision);
+}
+function serializeExternalIdentity(identity) {
+	return JSON.stringify([
+		identity.provider,
+		identity.issuer,
+		identity.subject
+	]);
+}
+function parseStoredExternalIdentity(serialized) {
+	const raw = JSON.parse(serialized);
+	if (!Array.isArray(raw) || raw.length !== 3) throw new Error("Invalid external identity");
+	const [provider, issuer, subject] = raw;
+	return parseExternalIdentity({
+		provider,
+		issuer,
+		subject
+	});
+}
+function parseExternalIdentity(raw) {
+	const value = requireRecord(raw, "external identity");
+	const provider = value.provider;
+	const issuer = requireCanonicalString(value.issuer, "issuer");
+	const subject = requireCanonicalString(value.subject, "subject");
+	switch (provider) {
+		case "google":
+			if (issuer !== "https://accounts.google.com") throw new Error("Invalid Google issuer");
+			return {
+				provider,
+				issuer,
+				subject
+			};
+		case "application": return {
+			provider,
+			issuer,
+			subject
+		};
+		default: throw new Error("Invalid external identity provider");
+	}
+}
+function assertNever(value) {
+	throw new Error(`Unsupported external authentication provider: ${String(value)}`);
 }
 function parseExternalWalletAuthentication(value) {
 	const record = requireRecord(value, "external authentication");
 	const walletId = parseWalletId(record.walletId);
-	if (!walletId.ok || record.kind !== "external_authenticated" || record.provider !== "google" || record.permission !== "wallet_settings_read" || "authMethod" in record) throw new Error("External authentication is invalid");
+	if (!walletId.ok || record.kind !== "external_authenticated" || record.provider !== "google" && record.provider !== "application" || record.permission !== "wallet_settings_read" || "authMethod" in record) throw new Error("External authentication is invalid");
 	return {
 		kind: "external_authenticated",
 		walletId: walletId.value,
 		sessionId: requireCanonicalString(record.sessionId, "sessionId"),
 		associationId: requireCanonicalString(record.associationId, "associationId"),
 		environmentId: requireCanonicalString(record.environmentId, "environmentId"),
-		provider: "google",
+		provider: record.provider,
 		permission: "wallet_settings_read",
 		expiresAtMs: parseUnixMs(record.expiresAtMs, "expiresAtMs")
 	};
@@ -40,6 +113,6 @@ function externalAuthFailure(code) {
 	};
 }
 //#endregion
-export { EXTERNAL_AUTH_PATH, externalAuthFailure, parseExternalAuthConfiguration, parseExternalWalletAuthentication };
+export { EXTERNAL_AUTH_PATH, externalAuthFailure, parseExternalAuthConfiguration, parseExternalAuthProvider, parseExternalWalletAuthentication, parseStoredExternalIdentity, serializeExternalIdentity };
 
 //# sourceMappingURL=externalAuth.js.map

package/dist/esm/shared-ts/src/authorization/index.js

@@ -1,6 +1,6 @@
+import "./walletOwnerOperation.js";
 import "./capabilityKinds.js";
 import "./delegatedAuthority.js";
 import "./operationFingerprint.js";
 import "./walletAuthority.js";
-import "./walletCustodyOperation.js";
 import "./walletSessionIssuance.js";

package/dist/esm/shared-ts/src/authorization/{walletCustodyOperation.js → walletOwnerOperation.js}

@@ -1,8 +1,8 @@
 import { alphabetizeStringify } from "../utils/digests.js";
 import { sha256Utf8DigestB64u } from "../utils/canonicalPrimitives.js";
-//#region ../shared-ts/src/authorization/walletCustodyOperation.ts
+//#region ../shared-ts/src/authorization/walletOwnerOperation.ts
 /** Public challenge digest for a single wallet-administration factor proof. */
-async function computeWalletCustodyAdminChallengeDigest(input) {
+async function computeWalletOwnerAdminChallengeDigest(input) {
 	return sha256Utf8DigestB64u(`seams:wallet-custody:challenge:v1|${alphabetizeStringify({
 		walletId: input.walletId,
 		operation: input.operation,
@@ -11,6 +11,6 @@ async function computeWalletCustodyAdminChallengeDigest(input) {
 	})}`);
 }
 //#endregion
-export { computeWalletCustodyAdminChallengeDigest };
+export { computeWalletOwnerAdminChallengeDigest };
 
-//# sourceMappingURL=walletCustodyOperation.js.map
+//# sourceMappingURL=walletOwnerOperation.js.map

package/dist/esm/shared-ts/src/wallet-recovery/index.js

@@ -1,10 +1,10 @@
-import "./recoveryCodeReservation.js";
 import "../utils/emailOtpRecoveryKey.js";
+import "./recoveryCodeLocator.js";
+import "./recoveryCodeReservation.js";
 import "./recoveryKeyId.js";
+import "./walletRecoveryEcdsaPossession.js";
 import "./backupAcknowledgement.js";
 import "./recoveryCodes.js";
 import "./walletRecoveryEnvelopeSet.js";
-import "./recoveryCodeLocator.js";
-import "./walletRecoveryEcdsaPossession.js";
 import "./walletRecoveryRotation.js";
 import "./walletRecoveryCommittedProjection.js";

package/dist/types/shared-ts/src/auth/externalAuth.d.ts

@@ -1,16 +1,55 @@
 import { type WalletId } from '../utils/domainIds';
+import { type Ed25519PublicKeyB64u } from '../passkey-custody/primitives';
 import type { ReadonlyExclusiveUnion } from '../utils/variant';
+import { type DigestB64u } from '../utils/canonicalPrimitives';
 export declare const EXTERNAL_AUTH_PATH = "/wallet/external-auth";
-export type ExternalAuthConfiguration = ReadonlyExclusiveUnion<{
+export type ExternalAuthProvider = ReadonlyExclusiveUnion<{
     kind: 'disabled';
-    revision: number;
 } | {
     kind: 'google';
-    revision: number;
     clientId: string;
+} | {
+    kind: 'application';
+    issuer: string;
+    publicKeyB64u: Ed25519PublicKeyB64u;
+}>;
+export type ExternalAuthConfiguration = ExternalAuthProvider & Readonly<{
+    revision: number;
+}>;
+export type ExternalIdentity = ReadonlyExclusiveUnion<{
+    provider: 'google';
+    issuer: 'https://accounts.google.com';
+    subject: string;
+} | {
+    provider: 'application';
+    issuer: string;
+    subject: string;
+}>;
+export type ExternalIdentityProof = ReadonlyExclusiveUnion<{
+    kind: 'google';
+    idToken: string;
+} | {
+    kind: 'application';
+    assertion: string;
 }>;
+export declare function parseExternalAuthProvider(raw: unknown): ExternalAuthProvider;
 export declare function parseExternalAuthConfiguration(raw: unknown): ExternalAuthConfiguration;
-type ExternalAuthFailureCode = 'invalid_request' | 'invalid_credential' | 'access_denied' | 'expired' | 'superseded' | 'unavailable' | 'rate_limited';
+export declare function serializeExternalIdentity(identity: ExternalIdentity): string;
+export declare function parseStoredExternalIdentity(serialized: string): ExternalIdentity;
+export type ExternalOwnerChallenge = Readonly<{
+    walletId: WalletId;
+    attemptId: string;
+    identity: ExternalIdentity;
+    challengeB64u: DigestB64u;
+    expiresAtMs: number;
+}> & ReadonlyExclusiveUnion<{
+    kind: 'associate';
+} | {
+    kind: 'unlink';
+    associationId: string;
+}>;
+export declare function parseExternalOwnerChallenge(raw: unknown): ExternalOwnerChallenge;
+type ExternalAuthFailureCode = 'invalid_request' | 'invalid_credential' | 'access_denied' | 'expired' | 'superseded' | 'unavailable' | 'rate_limited' | 'cancelled';
 export type ExternalAuthResult<T> = ReadonlyExclusiveUnion<{
     ok: true;
     value: T;
@@ -29,7 +68,9 @@ export type ExternalAuthenticateInput = ReadonlyExclusiveUnion<{
     attemptId: string;
     code: string;
 }>;
-export type ExternalAuthAttempt = Readonly<{
+export type ExternalAuthPurpose = 'authenticate' | 'associate';
+export type ExternalAuthAttempt<Purpose extends ExternalAuthPurpose = 'authenticate'> = Readonly<{
+    purpose: Purpose;
     attemptId: string;
     walletId: WalletId;
     expiresAtMs: number;
@@ -41,9 +82,11 @@ export type ExternalAuthCommand = ReadonlyExclusiveUnion<{
     action: 'prepare';
     walletId: string;
 } | {
-    action: 'associate';
+    action: 'prepare_association';
     walletId: string;
-    idToken: string;
+} | {
+    action: 'associate';
+    input: ExternalAuthenticateInput;
 } | {
     action: 'unlink';
     walletId: string;
@@ -56,7 +99,7 @@ export type ExternalWalletAuthentication = Readonly<{
     sessionId: string;
     associationId: string;
     environmentId: string;
-    provider: 'google';
+    provider: ExternalIdentity['provider'];
     permission: 'wallet_settings_read';
     expiresAtMs: number;
     authMethod?: never;

package/dist/types/shared-ts/src/authorization/index.d.ts

@@ -1,7 +1,7 @@
 export * from './capabilityKinds';
 export * from './delegatedAuthority';
 export * from './operationFingerprint';
-export * from './walletCustodyOperation';
+export * from './walletOwnerOperation';
 export * from './walletAuthority';
 export * from './walletSessionIssuance';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/shared-ts/src/authorization/walletOwnerOperation.d.ts

@@ -0,0 +1,10 @@
+import { type DigestB64u } from '../utils/canonicalPrimitives';
+export type WalletOwnerAdminOperation = 'external_identity_associate' | 'external_identity_unlink' | 'credentials_list' | 'credential_label' | 'recovery_rotate' | 'recovery_read' | 'recovery_status' | 'recovery_backup_acknowledge';
+/** Public challenge digest for a single wallet-administration factor proof. */
+export declare function computeWalletOwnerAdminChallengeDigest(input: {
+    readonly walletId: string;
+    readonly operation: WalletOwnerAdminOperation;
+    readonly payload: Record<string, unknown>;
+    readonly requestOrigin: string;
+}): Promise<DigestB64u>;
+//# sourceMappingURL=walletOwnerOperation.d.ts.map

package/dist/types/shared-ts/src/utils/registrationEstablishedSession.d.ts

@@ -72,6 +72,10 @@ export type RegistrationEstablishedSessionV2 = {
     readonly tokens: RegistrationEstablishedSessionProjectionTokensV2;
 };
 export type RegistrationEstablishedSessionResultV2 = {
+    readonly kind: 'owner_operations';
+    readonly walletId: WalletId;
+    readonly session?: never;
+} | {
     readonly kind: 'issued';
     readonly session: RegistrationEstablishedSessionV2;
 } | {

package/dist/types/shared-ts/src/utils/registrationIntent.d.ts

@@ -18,7 +18,9 @@ export type RuntimePolicyScopeLike = {
     envId: string;
     signingRootVersion?: string;
 };
+export type RegistrationCompletion = 'wallet_session' | 'owner_operations';
 export type RegistrationIntentV1 = {
+    completion: RegistrationCompletion;
     version: 'registration_intent_v1';
     walletId: WalletId;
     authMethod: RegistrationAuthMethodInput;

package/dist/types/shared-ts/src/utils/walletManagementProtocol.d.ts

@@ -1,3 +1,3 @@
 export declare const WALLET_MANAGEMENT_PROTOCOL_HEADER = "X-Seams-Wallet-Protocol";
-export declare const WALLET_MANAGEMENT_PROTOCOL_VERSION = "4";
+export declare const WALLET_MANAGEMENT_PROTOCOL_VERSION = "5";
 //# sourceMappingURL=walletManagementProtocol.d.ts.map

package/dist/types/wallet-server/src/application-auth.d.ts

@@ -0,0 +1,3 @@
+/** Backend-only application-session assertions for the external-auth exchange. */
+export { createApplicationAuthAssertion } from './auth/applicationAuth';
+//# sourceMappingURL=application-auth.d.ts.map

package/dist/types/wallet-server/src/auth/applicationAuth.d.ts

@@ -0,0 +1,29 @@
+import type { ExternalAuthConfiguration, ExternalAuthPurpose, ExternalAuthResult, ExternalIdentity } from '../../../shared-ts/src/auth/externalAuth';
+import type { Variant } from '../../../shared-ts/src/utils/variant';
+type ApplicationTrust = Variant<ExternalAuthConfiguration, 'kind', 'application'>;
+/** Called only by the application's authenticated backend with its enrolled issuer key. */
+export declare function createApplicationAuthAssertion(input: {
+    readonly privateKey: CryptoKey;
+    readonly issuer: string;
+    readonly subject: string;
+    readonly environmentId: string;
+    readonly walletId: string;
+    readonly attemptId: string;
+    readonly nowMs: number;
+    readonly sessionExpiresAtMs: number;
+    readonly purpose: ExternalAuthPurpose;
+}): Promise<string>;
+export declare function verifyApplicationAuthAssertion(input: {
+    readonly trust: ApplicationTrust;
+    readonly assertion: string;
+    readonly environmentId: string;
+    readonly walletId: string;
+    readonly attemptId: string;
+    readonly nowMs: number;
+    readonly purpose: ExternalAuthPurpose;
+}): Promise<ExternalAuthResult<{
+    identity: Variant<ExternalIdentity, 'provider', 'application'>;
+    expiresAtMs: number;
+}>>;
+export {};
+//# sourceMappingURL=applicationAuth.d.ts.map