@oxy.so/core 1.5.1 → 1.6.0

package/dist/types/HttpService.d.ts

@@ -111,6 +111,17 @@ export declare class HttpService {
      * fixed deadline that could not shrink once the token expired mid-cooldown.
      */
     private lastRefreshFailureAt;
+    /**
+     * Whether the last refresh failure was the server answering 429. Selects
+     * {@link RATE_LIMITED_REFRESH_COOLDOWN_MS} over the two token-state cooldowns
+     * for the NEXT attempt, and is cleared by any success or any other failure.
+     *
+     * A boolean beside {@link lastRefreshFailureAt} rather than a stored deadline,
+     * for the same reason that field gives: the cooldown stays a function of the
+     * current state, so it can still shorten if the situation changes underneath
+     * it, and there is exactly one timestamp to reason about.
+     */
+    private lastRefreshWasRateLimited;
     private authRefreshHandler;
     private accessTokenProvider;
     private deviceSecretMintInFlight;
@@ -266,6 +277,19 @@ export declare class HttpService {
      */
     private getAuthHeader;
     refreshAccessToken(reason: AuthRefreshReason): Promise<string | null>;
+    /**
+     * Report that the refresh/mint endpoint answered 429 Too Many Requests, so the
+     * next attempt waits {@link RATE_LIMITED_REFRESH_COOLDOWN_MS} instead of one of
+     * the token-state cooldowns.
+     *
+     * Called by the refresh handler (`refreshDeviceSecretArm`) from inside the
+     * `authRefreshHandler` call, because the handler's `Promise<string | null>`
+     * contract cannot carry WHY a refresh failed and 429 is the one failure whose
+     * correct retry interval is set by the server rather than by the token.
+     *
+     * Public because the handler lives in `session/refresh.ts`, not on this class.
+     */
+    noteRefreshRateLimited(): void;
     /**
      * Whether the CURRENT stored access token is already past its `exp`. Drives
      * the shorter post-failure refresh cooldown ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}):

package/dist/types/crypto/identityMove.d.ts

@@ -1,20 +1,18 @@
 /**
- * Identity move — the crypto of taking a web identity into Commons.
+ * Identity move — the crypto of giving a web root to Commons (ADR 0024 D6).
  *
- * Both carriers run this: `id.oxy.so` (the initiator, holding the identity) and
- * Commons (the responder, receiving it). The relay in between sees two ephemeral
- * public keys and ciphertext; the 6-digit SAS both screens show is what makes a
- * relay that swapped a key visible to the person.
+ * Both sides run this: the web holder (the initiator, holding the root) and
+ * Commons (the responder, receiving it). The relay in between sees a commitment,
+ * two ephemeral public keys and ciphertext. The initiator commits to its key
+ * before the responder chooses one and reveals it only afterwards, so the 6-digit
+ * code both screens show exposes a relay that substituted a key — it cannot grind
+ * one until the codes agree. The receipt binds the move, the root, both keys and
+ * the ciphertext actually relayed.
  *
  * PURE: no storage, no network. Contract: `@oxy.so/contracts` `identityMove`.
  */
 import './polyfill';
-import { type OpenedWebIdentity } from './webIdentityCarrier';
-/** Actions the identity key signs during a move. */
-export declare const IDENTITY_MOVE_ACTIONS: {
-    readonly seal: "identity_move_seal";
-    readonly received: "identity_move_received";
-};
+import { type OpenedMnemonicIdentity } from './webIdentityCarrier';
 /** A fresh ephemeral key pair for one move. Keep the private key in memory only. */
 export declare function generateMoveEphemeralKeyPair(): {
     privateKey: string;
@@ -22,10 +20,44 @@ export declare function generateMoveEphemeralKeyPair(): {
 };
 /** The symmetric key both sides derive: HKDF(ECDH, salt = moveId). */
 export declare function deriveMoveKey(ownEphemeralPrivateKey: string, otherEphemeralPublicKey: string, moveId: string): Uint8Array;
-/** The 6-digit code both screens show, bound to the move and both ephemeral keys in their roles. */
-export declare function deriveMoveSas(moveId: string, initiatorEphemeralPublicKey: string, responderEphemeralPublicKey: string): string;
-/** Initiator: seal the identity's entropy for the responder. */
-export declare function sealIdentityForMove(identity: Pick<OpenedWebIdentity, 'mnemonic' | 'publicKey'>, moveKey: Uint8Array, moveId: string): {
+/** Initiator: commit to the ephemeral key before anyone else's key is known. The nonce stays in memory until the reveal. */
+export declare function createMoveCommitment(initiatorEphemeralPublicKey: string): {
+    commitment: string;
+    nonce: string;
+};
+/** Responder: does the revealed key match the commitment read before joining? */
+export declare function verifyMoveCommitment(initiatorEphemeralPublicKey: string, nonce: string, commitment: string): boolean;
+/** The 6-digit code, bound to the move, both keys in their roles, and the commitment. */
+export declare function deriveMoveSas(input: {
+    moveId: string;
+    initiatorEphemeralPublicKey: string;
+    responderEphemeralPublicKey: string;
+    initiatorCommitment: string;
+}): string;
+/** The digest a receipt binds: what was actually relayed. */
+export declare function digestMoveCiphertext(sealed: {
+    nonce: string;
+    ciphertext: string;
+}): string;
+export interface MoveReceiptClaims {
+    moveId: string;
+    rootPublicKey: string;
+    initiatorEphemeralPublicKey: string;
+    responderEphemeralPublicKey: string;
+    ciphertextDigest: string;
+}
+/**
+ * Responder: sign the receipt with a signer that reads the root back from durable
+ * storage (Commons passes its keychain signer), so a receipt exists only for a
+ * root that was actually stored.
+ */
+export declare function signMoveReceipt(sign: (message: string) => Promise<string>, claims: MoveReceiptClaims): Promise<{
+    signature: string;
+}>;
+/** Initiator: is this receipt the root's, for exactly this move and ciphertext? */
+export declare function verifyMoveReceipt(claims: MoveReceiptClaims, signature: string): Promise<boolean>;
+/** Initiator: seal the phrase entropy (12–24 words) for the responder. */
+export declare function sealIdentityForMove(identity: Pick<OpenedMnemonicIdentity, 'mnemonic' | 'publicKey'>, moveKey: Uint8Array, moveId: string): {
     nonce: string;
     ciphertext: string;
 };
@@ -36,23 +68,7 @@ export declare function sealIdentityForMove(identity: Pick<OpenedWebIdentity, 'm
 export declare function openMovedIdentity(sealed: {
     nonce: string;
     ciphertext: string;
-}, moveKey: Uint8Array, moveId: string, expectedPublicKey: string): OpenedWebIdentity;
-/** The exact bytes a move proof or receipt signs. */
-export declare function buildMoveMessage(action: string, moveId: string, timestamp: number): string;
-/** Sign a move action with the identity key. */
-export declare function signMoveAction(identity: Pick<OpenedWebIdentity, 'privateKey'>, action: string, moveId: string, timestamp?: number): Promise<{
-    signature: string;
-    timestamp: number;
-}>;
-/**
- * Initiator: is this receipt really from the identity? Checked locally with the
- * identity's public key, so a server that claims "completed" without Commons
- * having the key cannot make the web destroy its copy.
- */
-export declare function verifyMoveReceipt(publicKey: string, moveId: string, receipt: {
-    signature: string;
-    timestamp: number;
-}): Promise<boolean>;
+}, moveKey: Uint8Array, moveId: string, expectedPublicKey: string): OpenedMnemonicIdentity;
 /** The QR payload for a move. */
 export declare function buildMoveQrPayload(moveId: string): string;
 /** The move id in a scanned payload, or `null` when it is not a move QR. */

package/dist/types/crypto/identityProof.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Signing the one identity-proof format (ADR 0024 D7).
+ *
+ * The bytes come from `@oxy.so/contracts` `buildIdentityProofMessage`, which the
+ * API verifies against; payload digests hash `canonicalJson`. Nothing here builds
+ * its own JSON.
+ */
+import './polyfill';
+import { type IdentityProof, type IdentityProofClaims } from '@oxy.so/contracts';
+/** SHA-256 hex of the canonical JSON of `payload` — the `payloadDigest` claim. */
+export declare function digestIdentityPayload(payload: unknown): string;
+/** Sign `claims` with the root, producing the proof as it travels. */
+export declare function signIdentityProof(identity: {
+    privateKey: string;
+    publicKey: string;
+}, claims: IdentityProofClaims): Promise<IdentityProof>;

package/dist/types/crypto/webIdentityCarrier.d.ts

@@ -1,18 +1,18 @@
 /**
- * Web identity carrier — the crypto of "one identity, two carriers".
+ * Web identity holder — the crypto of a browser holding a personal root (ADR 0024).
  *
- * An Oxy identity is a BIP-39 mnemonic; its seed's first 32 bytes are the
- * secp256k1 key (`recoveryPhrase.ts`). Commons keeps that key in the device
- * keychain. This module lets a browser carry the SAME identity without Oxy ever
- * being able to use it:
+ * An Oxy root is usually a BIP-39 mnemonic whose seed's first 32 bytes are the
+ * secp256k1 key (`recoveryPhrase.ts`), and for a few imported identities a raw
+ * private key with no phrase. Commons keeps it in the device keychain. This
+ * module lets a browser hold the SAME root without Oxy ever being able to use it:
  *
- *   entropy ──AEAD(DEK)──▶ sealedEntropy
+    secret  ──AEAD(DEK)──▶ sealed secret        (phrase entropy or raw key)
  *   DEK     ──AEAD(KEK_i)─▶ wraps[i]            KEK_i = HKDF(PRF output of passkey i)
  *
  * The PRF output is produced inside the user's authenticator, behind user
  * verification, and never leaves the page that asked for it. The envelope is
- * therefore safe to store anywhere — the identity origin's IndexedDB and the
- * server copy alike — and opens only with a registered passkey or the phrase.
+ * therefore safe to store anywhere — the holder host's IndexedDB and the server
+ * copy alike — and opens only with a registered passkey or the recovery material.
  *
  * PURE: no storage, no network, no WebAuthn call, no platform globals beyond the
  * CSPRNG the AEAD polyfill guarantees. The caller runs the ceremony and hands the
@@ -22,7 +22,7 @@
  * Contract: `WebIdentityEnvelope` in `@oxy.so/contracts`.
  */
 import './polyfill';
-import { type WebIdentityEnvelope, type WebIdentityWrap } from '@oxy.so/contracts';
+import { type WebIdentityEnvelope } from '@oxy.so/contracts';
 /**
  * The PRF input every identity-carrier ceremony evaluates (`prf.eval.first`).
  *
@@ -31,6 +31,8 @@ import { type WebIdentityEnvelope, type WebIdentityWrap } from '@oxy.so/contract
  * scheme change bumps the label — and with it every KEK — instead of mutating it.
  */
 export declare const WEB_IDENTITY_PRF_INPUT: Uint8Array;
+/** A WebAuthn PRF output is 32 bytes (HMAC-SHA-256). Nothing shorter or longer is usable. */
+export declare const WEB_IDENTITY_PRF_OUTPUT_LENGTH = 32;
 /** Why an envelope did not open. Every value is a normal outcome a UI can explain. */
 export type WebIdentityUnlockFailure = 
 /** The passkey used is not one of the envelope's wraps. */
@@ -38,7 +40,7 @@ export type WebIdentityUnlockFailure =
 /**
  * The passkey IS listed but its PRF output does not open its wrap — a synced
  * copy returning a different PRF value, or a provider that silently changed it.
- * Recoverable with another passkey or the phrase.
+ * Recoverable with another passkey or the recovery material.
  */
  | 'prf-mismatch'
 /** The envelope itself is malformed or tampered with. */
@@ -47,39 +49,81 @@ export declare class WebIdentityUnlockError extends Error {
     readonly failure: WebIdentityUnlockFailure;
     constructor(failure: WebIdentityUnlockFailure, message: string);
 }
-/** The identity in usable form. Hold it for one operation, then {@link wipeBytes}. */
-export interface OpenedWebIdentity {
+/** A root that came from a BIP-39 phrase (12–24 words). Hold it for one operation, then wipe. */
+export interface OpenedMnemonicIdentity {
+    kind: 'mnemonic';
     mnemonic: string;
-    /** 32-byte secp256k1 private key, lowercase hex. */
+    /** 32-byte secp256k1 private key, lowercase hex (`seed[0:32]`). */
     privateKey: string;
     /** Uncompressed SEC1 public key, lowercase hex (Oxy's canonical form). */
     publicKey: string;
 }
+/**
+ * A root that was imported as a raw private key and never had a phrase. It has
+ * no mnemonic, and nothing may ever derive or display one for it (ADR 0024 D5).
+ */
+export interface OpenedRawKeyIdentity {
+    kind: 'raw-key';
+    mnemonic: null;
+    privateKey: string;
+    publicKey: string;
+}
+/** The identity in usable form. Hold it for one operation, then wipe it. */
+export type OpenedWebIdentity = OpenedMnemonicIdentity | OpenedRawKeyIdentity;
+/** Material a person can recover a root from. */
+export type WebIdentityRecoveryMaterial = {
+    kind: 'mnemonic';
+    mnemonic: string;
+} | {
+    kind: 'raw-key';
+    privateKey: string;
+};
 /** Overwrite a buffer holding secret material. Best effort — JS gives no stronger guarantee. */
 export declare function wipeBytes(bytes: Uint8Array): void;
+/** Best-effort removal of secret strings from an opened identity. */
+export declare function wipeOpenedIdentity(identity: OpenedWebIdentity): void;
+/** Normalize a typed phrase: trimmed, lowercase, single spaces. */
+export declare function normalizeMnemonic(mnemonic: string): string;
 /**
  * Derive the identity from a mnemonic exactly as Commons does
- * (`RecoveryPhraseService`): seed → first 32 bytes → secp256k1.
+ * (`RecoveryPhraseService`): seed → first 32 bytes → secp256k1. Any standard
+ * BIP-39 length (12, 15, 18, 21, 24 words) is accepted; the derivation does not
+ * depend on the length.
  */
-export declare function deriveIdentityFromMnemonic(mnemonic: string): OpenedWebIdentity;
+export declare function deriveIdentityFromMnemonic(mnemonic: string): OpenedMnemonicIdentity;
+/** A raw 32-byte private key (hex, optional `0x`) as an identity. Never gains a phrase. */
+export declare function deriveIdentityFromPrivateKey(privateKey: string): OpenedRawKeyIdentity;
+/**
+ * Read what a person typed as recovery material: a BIP-39 phrase, or a 64-hex
+ * private key. Throws `Invalid recovery material` for anything else.
+ */
+export declare function parseRecoveryMaterial(input: string): WebIdentityRecoveryMaterial;
+/** Derive the identity recovery material names. */
+export declare function deriveIdentityFromRecoveryMaterial(material: WebIdentityRecoveryMaterial): OpenedWebIdentity;
 /** A brand-new 12-word identity. Nothing is persisted. */
-export declare function generateWebIdentity(): OpenedWebIdentity;
+export declare function generateWebIdentity(): OpenedMnemonicIdentity;
 /** A fresh random data key for a new envelope. */
 export declare function generateDataKey(): Uint8Array;
+/** Whether `bytes` is a usable PRF output: exactly 32 bytes. */
+export declare function isUsablePrfOutput(bytes: Uint8Array | null | undefined): bytes is Uint8Array;
 /** The key-encryption key a passkey's PRF output yields for its own wrap. */
 export declare function deriveKeyEncryptionKey(prfOutput: Uint8Array, credentialId: string): Uint8Array;
-/** Wrap `dataKey` for one passkey. */
-export declare function wrapDataKey(dataKey: Uint8Array, prfOutput: Uint8Array, credentialId: string, publicKey: string, now?: Date): WebIdentityWrap;
+/** One passkey's contribution to an envelope. */
+export interface WrapInput {
+    prfOutput: Uint8Array;
+    credentialId: string;
+    /** The RP ID the passkey lives under; bound into the wrap. */
+    rpId: string;
+    /** Set when this PRF output came from a ceremony separate from the one that created the wrap. */
+    verifiedAt?: string;
+}
 /**
  * Seal an identity into a new envelope that opens with the given passkey.
  *
  * Returns the data key too, so the caller can add further wraps in the same
  * session; wipe it when done.
  */
-export declare function sealWebIdentity(identity: Pick<OpenedWebIdentity, 'mnemonic' | 'publicKey'>, firstWrap: {
-    prfOutput: Uint8Array;
-    credentialId: string;
-}, now?: Date): {
+export declare function sealWebIdentity(identity: OpenedWebIdentity, firstWrap: WrapInput, now?: Date): {
     envelope: WebIdentityEnvelope;
     dataKey: Uint8Array;
 };
@@ -88,36 +132,19 @@ export declare function unwrapDataKey(envelope: WebIdentityEnvelope, prfOutput:
 /**
  * Open an envelope with its data key.
  *
- * The derived public key is checked against the envelope's own: a sealed entropy
+ * The derived public key is checked against the envelope's own: a sealed secret
  * that decrypts into a different identity is treated as corruption, never used.
  */
 export declare function openWebIdentity(envelope: WebIdentityEnvelope, dataKey: Uint8Array): OpenedWebIdentity;
 /** Unwrap and open in one step. */
 export declare function unlockWebIdentity(envelope: WebIdentityEnvelope, prfOutput: Uint8Array, credentialId: string): OpenedWebIdentity;
 /** Add (or replace) one passkey's wrap. Requires the data key of an unlocked envelope. */
-export declare function addWrap(envelope: WebIdentityEnvelope, dataKey: Uint8Array, prfOutput: Uint8Array, credentialId: string, now?: Date): WebIdentityEnvelope;
-/** Remove one passkey's wrap. The last wrap can never be removed — an envelope nobody can open is a loss. */
-export declare function removeWrap(envelope: WebIdentityEnvelope, credentialId: string): WebIdentityEnvelope;
+export declare function addWrap(envelope: WebIdentityEnvelope, dataKey: Uint8Array, wrapInput: WrapInput, now?: Date): WebIdentityEnvelope;
 /**
- * The message an identity key signs to authorize an account action
- * (`link_identity`, `web_envelope_delete`, …): `JSON.stringify({ action, userId,
- * timestamp })`, byte-identical to what the API reconstructs.
+ * Record that a wrap's passkey opened the envelope in a ceremony of its own. The
+ * AEAD does not cover `verifiedAt`; it is holder metadata the owner writes with a
+ * root proof, not a cryptographic claim.
  */
-export declare function buildIdentityActionMessage(action: string, userId: string, timestamp: number): string;
-/** Sign an identity-action message with an opened identity's key. */
-export declare function signIdentityAction(identity: Pick<OpenedWebIdentity, 'privateKey'>, action: string, userId: string, timestamp?: number): Promise<{
-    signature: string;
-    timestamp: number;
-}>;
-/**
- * The 6-digit short authentication string both sides of an identity transfer show.
- *
- * Bound to the pairing and to BOTH ephemeral public keys in their roles, so a relay
- * that substitutes either key produces a different code on each screen. The user
- * comparing the two codes is what makes the transfer safe against the relay itself.
- */
-export declare function deriveTransferSas(input: {
-    pairingId: string;
-    initiatorEphemeralPublicKey: string;
-    responderEphemeralPublicKey: string;
-}): string;
+export declare function markWrapVerified(envelope: WebIdentityEnvelope, credentialId: string, now?: Date): WebIdentityEnvelope;
+/** Remove one passkey's wrap. The last wrap can never be removed — an envelope nobody can open is a loss. */
+export declare function removeWrap(envelope: WebIdentityEnvelope, credentialId: string): WebIdentityEnvelope;

package/dist/types/index.d.ts

@@ -30,7 +30,6 @@ export type { CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, Co
 export type { PushTokenPlatform, RegisterPushTokenInput, } from './mixins/OxyServices.notifications';
 export type { ServiceApp, ServiceActingAsVerification, OxyAuthRefusal } from './mixins/OxyServices.utility';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
-export type { InitDeviceTransferResult, DeviceTransferOutcome, } from './mixins/OxyServices.deviceTransfer';
 export type { BulkFollowEntry, BulkFollowResult, BulkUnfollowEntry, BulkUnfollowResult, FollowMutationResult, ViewerGraph, } from './mixins/OxyServices.user';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity';
@@ -44,7 +43,7 @@ export type { StoreCategory, StoreRating, StoreListingSummary, StoreListingDetai
 export type { AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, RotateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
 export { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './mixins/OxyServices.accounts';
 export { buildUserDid } from './mixins/OxyServices.identity';
-export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './mixins/OxyServices.identity';
+export type { IdentityRecordType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './mixins/OxyServices.identity';
 export { parseIdPayload, parseAttestPayload, verifyPublicCardAttestation, } from './mixins/OxyServices.civic';
 export type { CivicCardResult, IdCardRef, AttestQrPayload, ParsedAttestPayload, SubmitRealLifeAttestationInput, DenyValidationResult, VouchForPersonInput, WithdrawVouchResult, IssueCredentialInput, RevokeCredentialResult, } from './mixins/OxyServices.civic';
 export type { UserNodeStatus, UserNodeMode, UserNodeController, UserNodeLivenessStatus, RegisterNodeInput, RemoveNodeResult } from './mixins/OxyServices.nodes';
@@ -70,9 +69,11 @@ export { hkdfSha256 } from './crypto/kdf';
 export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH, } from './crypto/aead';
 export type { AeadResult } from './crypto/aead';
 export { deriveSharedSecret } from './crypto/ecdh';
-export { WEB_IDENTITY_PRF_INPUT, WebIdentityUnlockError, addWrap, buildIdentityActionMessage, deriveIdentityFromMnemonic, deriveKeyEncryptionKey, deriveTransferSas, generateDataKey, generateWebIdentity, openWebIdentity, removeWrap, sealWebIdentity, signIdentityAction, unlockWebIdentity, unwrapDataKey, wipeBytes, wrapDataKey, } from './crypto/webIdentityCarrier';
-export type { OpenedWebIdentity, WebIdentityUnlockFailure } from './crypto/webIdentityCarrier';
-export { IDENTITY_MOVE_ACTIONS, buildMoveMessage, buildMoveQrPayload, deriveMoveKey, deriveMoveSas, generateMoveEphemeralKeyPair, openMovedIdentity, parseMoveQrPayload, sealIdentityForMove, signMoveAction, verifyMoveReceipt, } from './crypto/identityMove';
+export { WEB_IDENTITY_PRF_INPUT, WebIdentityUnlockError, WEB_IDENTITY_PRF_OUTPUT_LENGTH, addWrap, deriveIdentityFromMnemonic, deriveIdentityFromPrivateKey, deriveIdentityFromRecoveryMaterial, deriveKeyEncryptionKey, generateDataKey, generateWebIdentity, isUsablePrfOutput, markWrapVerified, normalizeMnemonic, openWebIdentity, parseRecoveryMaterial, removeWrap, sealWebIdentity, unlockWebIdentity, unwrapDataKey, wipeBytes, wipeOpenedIdentity, } from './crypto/webIdentityCarrier';
+export type { OpenedMnemonicIdentity, OpenedRawKeyIdentity, OpenedWebIdentity, WebIdentityRecoveryMaterial, WebIdentityUnlockFailure, WrapInput, } from './crypto/webIdentityCarrier';
+export { digestIdentityPayload, signIdentityProof } from './crypto/identityProof';
+export { buildMoveQrPayload, createMoveCommitment, deriveMoveKey, deriveMoveSas, digestMoveCiphertext, generateMoveEphemeralKeyPair, openMovedIdentity, parseMoveQrPayload, sealIdentityForMove, signMoveReceipt, verifyMoveCommitment, verifyMoveReceipt, } from './crypto/identityMove';
+export type { MoveReceiptClaims } from './crypto/identityMove';
 export { DeviceManager } from './utils/deviceManager';
 export type { DeviceFingerprint, StoredDeviceInfo } from './utils/deviceManager';
 export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, BatchFileAccessEntry, BatchFileAccessResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceLinkedSession, DeviceLinkedSessionsResponse, DeviceLinkedSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
@@ -141,7 +142,7 @@ export { AccountNotOnDeviceError } from './mixins/OxyServices.deviceBoot';
 export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';
 export type { RefreshDeps, TokenRefreshSchedulerHandle, DeviceSecretMintOutcome } from './session/refresh';
 export { OxyInferenceClient, OxyInferenceError, OxyInferenceProtocolError, OXY_INFERENCE_BASE_URL, } from './inference/OxyInferenceClient';
-export type { OxyInferenceClientOptions, OxyInferenceCredential, OxyInferenceFetch, OxyInferenceRequestOptions, OxyInferenceResponse, OxyGenerationReceipt, OxyResponsesRequest, } from './inference/OxyInferenceClient';
+export type { OxyInferenceClientOptions, OxyInferenceCredential, OxyInferenceFetch, OxyInferenceRequestOptions, OxyInferenceResponse, OxyGenerationReceipt, OxyResponsesRequest, OxySpeechRequest, OxySpeechResponse, } from './inference/OxyInferenceClient';
 export { runSessionColdBoot } from './boot/sessionColdBoot';
 export type { RunSessionColdBootOptions, SessionMode, SignedOutReason, DeviceBootSession, } from './boot/sessionColdBoot';
 export { packageInfo } from './constants/version';

package/dist/types/inference/OxyInferenceClient.d.ts

@@ -49,7 +49,7 @@
  * schema, so a rename on either side fails a build rather than a customer's
  * request.
  */
-import type { CurrencyCode, ExactDecimal, InferenceEnvironment, InferenceErrorCode, InferenceFinishReason, InferenceMessage, InferenceRequestOutcome, InferenceStreamEvent, ModelCatalogueEntry, ResponseFormat, RoutingPolicyReference, RoutingProfile, ToolChoice, ToolDefinition, UnitPrice, UsageQuantity, UsageSource } from '@oxy.so/contracts';
+import type { CurrencyCode, ExactDecimal, InferenceEnvironment, InferenceErrorCode, InferenceFinishReason, InferenceMessage, InferenceRequestOutcome, InferenceAudioMediaType, InferenceStreamEvent, InferenceSpeechParameters, ModelCatalogueEntry, ResponseFormat, RoutingPolicyReference, RoutingProfile, ToolChoice, ToolDefinition, UnitPrice, UsageQuantity, UsageSource } from '@oxy.so/contracts';
 /** The base URL of the Oxy API, when a caller names none. */
 export declare const OXY_INFERENCE_BASE_URL = "https://api.oxy.so";
 /**
@@ -110,6 +110,24 @@ export interface OxyResponsesRequest {
     /** Your own correlation id, echoed on the response. */
     readonly clientRequestId?: string;
 }
+/** Speech uses the same credential and delegation lane as responses. */
+export type OxySpeechRequest = ({
+    readonly model: string;
+    readonly routingProfileId?: never;
+} | {
+    readonly routingProfileId: string;
+    readonly model?: never;
+}) & {
+    readonly input: string;
+    readonly voice: string;
+    readonly response_format?: InferenceSpeechParameters['responseFormat'];
+    readonly speed?: number;
+};
+export interface OxySpeechResponse {
+    readonly audio: Uint8Array;
+    readonly mediaType: InferenceAudioMediaType;
+    readonly requestId: string;
+}
 export interface OxyInferenceRequestOptions {
     /**
      * Abort the request. The edge treats a client disconnect as a cancellation:
@@ -307,6 +325,8 @@ export declare class OxyInferenceClient {
      *   `code`, `retryable` and `requestId`.
      */
     respond(request: OxyResponsesRequest, options?: OxyInferenceRequestOptions): Promise<OxyInferenceResponse>;
+    /** Generate audio bytes through Oxy's authenticated inference edge. */
+    speech(request: OxySpeechRequest, options?: OxyInferenceRequestOptions): Promise<OxySpeechResponse>;
     /**
      * Stream one inference request from `POST /v1/responses`.
      *

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -5,6 +5,7 @@
  */
 import type { User } from '../models/interfaces';
 import type { LoginResult, CommonsDenyReason } from '@oxy.so/contracts';
+import { type IdentityProof, type WebIdentityEnvelope } from '@oxy.so/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
@@ -387,6 +388,28 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * @param apiSecret - Application credential secret (optional if configureServiceAuth was called)
          */
         getServiceToken(apiKey?: string, apiSecret?: string): Promise<string>;
+        /**
+         * Whether this process can prove what it is (ADR 0026).
+         *
+         * The check and the module that performs it are loaded LAZILY and only on a
+         * Node host. `@oxy.so/core`'s root barrel reaches React Native and Expo, and
+         * `server/workloadIdentity` imports `node:crypto` — a static import here
+         * would pull it into every mobile bundle for a path a phone can never take.
+         *
+         * @internal
+         */
+        _canUseWorkloadIdentity(): Promise<boolean>;
+        /**
+         * A service token obtained by attestation, cached like a credential's.
+         *
+         * The cache key is a constant, not a credential hash: a process has exactly
+         * one identity, so there is nothing to key on and nothing to keep separate.
+         * The secret-comparison guard the credential path applies has nothing to
+         * compare here, which is the point — there is no secret.
+         *
+         * @internal
+         */
+        _getWorkloadServiceToken(): Promise<string>;
         /**
          * Perform the actual /auth/service-token request and cache the result.
          * Separated so getServiceToken() can deduplicate concurrent calls.
@@ -799,6 +822,15 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             username?: string;
             deviceName?: string;
             deviceFingerprint?: string;
+            /**
+             * Sign-up only: the root created on the holder before this call, sealed
+             * under the passkey being registered, plus its `enroll_identity` proof
+             * (ADR 0024 D4). The account is created WITH it or not at all.
+             */
+            identity?: {
+                envelope: WebIdentityEnvelope;
+                proof: IdentityProof;
+            };
         }): Promise<{
             success: true;
             message: string;

package/dist/types/mixins/OxyServices.identity.d.ts

@@ -4,9 +4,9 @@
  * Provides typed access to Oxy's AtProto/Bluesky-flavoured identity &
  * portability layer:
  *  - DID resolution (`did:web:oxy.so:u:<userId>`, derived on demand by the API).
- *  - The auth-method ↔ DID verification-method mapping and its reversibility
- *    (link/unlink an identity key, link a password) via the existing
- *    `/auth/link` surface.
+ *  - The auth-method ↔ DID verification-method mapping (`GET /auth/methods`) and
+ *    passkey removal. A root is linked by the holder flows (ADR 0024) and never
+ *    unlinked; it is replaced by rotation.
  *  - Signed records: clients sign an envelope with their own cryptographic key
  *    (`SignatureService.signRecord` + the shared `canonicalize`) and publish it;
  *    anyone can fetch and verify it.
@@ -19,11 +19,11 @@
  * the API validates its output against, so producer and consumer cannot drift.
  *
  * Identity signing is NATIVE-ONLY: the private key lives in native secure
- * storage, so `linkIdentityKey`, `signRecord`, and `publishRecord` require an
+ * storage, so `signRecord` and `publishRecord` require an
  * on-device identity and throw on web (where `KeyManager.getPublicKey()` is
  * always `null`).
  */
-import type { AuthMethodsResponse, DidDocument, DomainVerificationInstructions, ExportBundle, OxySignedRecordType, SignedRecordEnvelope, VerifiedDomain } from '@oxy.so/contracts';
+import type { AuthMethodsResponse, IdentityRootStatus, DidDocument, DomainVerificationInstructions, ExportBundle, OxySignedRecordType, SignedRecordEnvelope, VerifiedDomain } from '@oxy.so/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PendingIdentityResult } from '../crypto/recoveryPhrase';
 /**
@@ -33,12 +33,7 @@ import { type PendingIdentityResult } from '../crypto/recoveryPhrase';
  * record set.
  */
 export type IdentityRecordType = OxySignedRecordType;
-/** Auth-method types that can be unlinked via {@link OxyServicesIdentityMixin}. */
-export type UnlinkableAuthMethodType = 'identity' | 'webauthn';
-/**
- * Result of a link/unlink auth-method mutation (`POST /auth/link`,
- * `DELETE /auth/link/:type`).
- */
+/** Result of an auth-method mutation (`DELETE /auth/link/webauthn/:id`). */
 export interface LinkAuthMethodResult {
     success: boolean;
     message: string;
@@ -145,31 +140,22 @@ export declare function OxyServicesIdentityMixin<T extends typeof OxyServicesBas
          */
         listAuthMethods(): Promise<AuthMethodsResponse>;
         /**
-         * Link the on-device cryptographic identity to the current account,
-         * upgrading it from custodial to self-sovereign. Signs a proof of private
-         * key ownership and posts it to `POST /auth/link`.
-         *
-         * NATIVE-ONLY: requires a stored identity (throws if `KeyManager` has no key
-         * or no user is authenticated). The signed payload is
-         * `JSON.stringify({ action: 'link_identity', userId, timestamp })` — the
-         * exact bytes the server reconstructs and verifies.
-         */
-        linkIdentityKey(): Promise<LinkAuthMethodResult>;
-        /**
-         * Unlink an authentication method from the current account. The server
-         * refuses to remove the last remaining method (the account would become
-         * inaccessible). Unlinking `identity` downgrades the account to custodial.
-         *
-         * @param type - The auth-method type to remove.
+         * The signed-in account's root readiness (ADR 0024 D5): whether a root is
+         * linked, how many passkeys can open the web holder, whether the root has a
+         * phrase and whether it is saved and was shown to recover it. Metadata only —
+         * nothing here can open the root — so any first-party surface may show a
+         * "save your recovery phrase" reminder from it.
          */
-        unlinkAuthMethod(type: UnlinkableAuthMethodType): Promise<LinkAuthMethodResult>;
+        getIdentityRootStatus(): Promise<IdentityRootStatus>;
         /**
          * Remove ONE passkey (WebAuthn credential) from the current account.
          *
-         * Passkeys are per-credential, so unlike {@link unlinkAuthMethod} (which
-         * removes an auth method by type) this targets a specific credential id.
+         * Passkeys are per-credential, so this targets a specific credential id.
          * The server refuses to remove the last remaining auth method (the account
          * would become inaccessible) and deletes the stored `WebauthnCredential`.
+         * A passkey that also opens the account's root on the web takes its wrap with
+         * it, and the ONLY such passkey is refused with
+         * `code: 'IDENTITY_LAST_WEB_HOLDER'` (ADR 0024 D6).
          *
          * @param credentialId - The passkey's public credential id
          *   (`AuthMethodEntry.credentialId`).

package/dist/types/mixins/index.d.ts

@@ -34,7 +34,6 @@ import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
 import { OxyServicesInferenceMixin } from './OxyServices.inference';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
-import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
  * `composeOxyServices()` produces a class whose instances expose all of
@@ -44,7 +43,7 @@ import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAgencyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAgencyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

package/dist/types/server/index.d.ts

@@ -38,3 +38,11 @@ export { isOfficialWebOrigin } from '../utils/officialOrigins';
 export { createEcosystemTraffic } from './traffic';
 export type { EcosystemTrafficOptions } from './traffic';
 export { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';
+/**
+ * Workload identity (ADR 0026): a first-party service asks Oxy for a service
+ * token by proving what it IS, with no api key and no secret. Server-only, and
+ * exported from this subpath rather than the root barrel because it reaches the
+ * container credentials endpoint.
+ */
+export { canAttestWorkloadIdentity, requestWorkloadServiceToken } from './workloadIdentity';
+export type { WorkloadServiceToken, WorkloadServiceTokenOptions } from './workloadIdentity';