@oxy.so/core 1.5.0 → 1.6.0

package/src/i18n/locales/ar-SA.json

@@ -108,6 +108,7 @@
     "loading": "جارٍ تحميل الحسابات...",
     "qrHeadline": "سجّل الدخول بهوية Oxy الخاصة بك",
     "signInWithOxy": "تسجيل الدخول باستخدام Oxy",
+    "signUpWithOxy": "التسجيل باستخدام Oxy",
     "useIdentityOnDevice": "لا تملك Commons؟ استخدم مفتاح مرور على هذا الجهاز بدلاً من ذلك",
     "getCommons": "احصل على Commons",
     "commonsNotInstalled": "لا تملك Commons؟ احصل على التطبيق لتسجيل الدخول بمعرّف Oxy الخاص بك.",

package/src/i18n/locales/ca-ES.json

@@ -108,6 +108,7 @@
     "loading": "S'estan carregant els comptes...",
     "qrHeadline": "Inicia sessió amb la teva identitat d'Oxy",
     "signInWithOxy": "Inicia sessió amb Oxy",
+    "signUpWithOxy": "Registra't amb Oxy",
     "useIdentityOnDevice": "No tens Commons? Fes servir una clau d'accés en aquest dispositiu",
     "getCommons": "Descarrega Commons",
     "commonsNotInstalled": "No tens Commons? Descarrega l'app per iniciar sessió amb el teu Oxy ID.",

package/src/i18n/locales/de-DE.json

@@ -108,6 +108,7 @@
     "loading": "Konten werden geladen...",
     "qrHeadline": "Melden Sie sich mit Ihrer Oxy-Identität an",
     "signInWithOxy": "Mit Oxy anmelden",
+    "signUpWithOxy": "Mit Oxy registrieren",
     "useIdentityOnDevice": "Kein Commons? Verwenden Sie stattdessen einen Passkey auf diesem Gerät",
     "getCommons": "Commons herunterladen",
     "commonsNotInstalled": "Kein Commons? Holen Sie sich die App, um sich mit Ihrer Oxy-ID anzumelden.",

package/src/i18n/locales/en-US.json

@@ -416,6 +416,7 @@
     "scanQr": "Scan QR code",
     "qrHeadline": "Sign in with your Oxy identity",
     "signInWithOxy": "Sign in with Oxy",
+    "signUpWithOxy": "Sign up with Oxy",
     "useIdentityOnDevice": "No Commons? Use a passkey on this device instead",
     "getCommons": "Get Commons",
     "commonsNotInstalled": "Don't have Commons? Get the app to sign in with your Oxy ID.",

package/src/i18n/locales/es-ES.json

@@ -656,6 +656,7 @@
     "scanQr": "Escanear código QR",
     "qrHeadline": "Inicia sesión con tu identidad de Oxy",
     "signInWithOxy": "Inicia sesión con Oxy",
+    "signUpWithOxy": "Regístrate con Oxy",
     "useIdentityOnDevice": "¿No tienes Commons? Usa una clave de acceso en este dispositivo",
     "getCommons": "Descargar Commons",
     "commonsNotInstalled": "¿No tienes Commons? Descarga la app para iniciar sesión con tu Oxy ID.",

package/src/i18n/locales/fr-FR.json

@@ -108,6 +108,7 @@
     "loading": "Chargement des comptes...",
     "qrHeadline": "Connectez-vous avec votre identité Oxy",
     "signInWithOxy": "Se connecter avec Oxy",
+    "signUpWithOxy": "S'inscrire avec Oxy",
     "useIdentityOnDevice": "Pas de Commons ? Utilisez une clé d'accès sur cet appareil",
     "getCommons": "Obtenir Commons",
     "commonsNotInstalled": "Pas de Commons ? Téléchargez l'app pour vous connecter avec votre Oxy ID.",

package/src/i18n/locales/it-IT.json

@@ -108,6 +108,7 @@
     "loading": "Caricamento account...",
     "qrHeadline": "Accedi con la tua identità Oxy",
     "signInWithOxy": "Accedi con Oxy",
+    "signUpWithOxy": "Registrati con Oxy",
     "useIdentityOnDevice": "Non hai Commons? Usa una passkey su questo dispositivo",
     "getCommons": "Ottieni Commons",
     "commonsNotInstalled": "Non hai Commons? Scarica l'app per accedere con il tuo Oxy ID.",

package/src/i18n/locales/ja-JP.json

@@ -108,6 +108,7 @@
     "loading": "アカウントを読み込み中...",
     "qrHeadline": "Oxy IDでサインイン",
     "signInWithOxy": "Oxyでサインイン",
+    "signUpWithOxy": "Oxyで登録",
     "useIdentityOnDevice": "Commonsがありませんか？このデバイスのパスキーを使用",
     "getCommons": "Commonsを入手",
     "commonsNotInstalled": "Commonsがありませんか？アプリを入手してOxy IDでサインインしましょう。",

package/src/i18n/locales/ko-KR.json

@@ -108,6 +108,7 @@
     "loading": "계정을 불러오는 중...",
     "qrHeadline": "Oxy ID로 로그인",
     "signInWithOxy": "Oxy로 로그인",
+    "signUpWithOxy": "Oxy로 가입하기",
     "useIdentityOnDevice": "Commons가 없으신가요? 이 기기의 패스키를 사용하세요",
     "getCommons": "Commons 다운로드",
     "commonsNotInstalled": "Commons가 없으신가요? 앱을 다운로드하여 Oxy ID로 로그인하세요.",

package/src/i18n/locales/pt-PT.json

@@ -108,6 +108,7 @@
     "loading": "A carregar contas...",
     "qrHeadline": "Inicie sessão com a sua identidade Oxy",
     "signInWithOxy": "Iniciar sessão com Oxy",
+    "signUpWithOxy": "Registar-se com Oxy",
     "useIdentityOnDevice": "Não tem o Commons? Use uma chave de acesso neste dispositivo",
     "getCommons": "Obter o Commons",
     "commonsNotInstalled": "Não tem o Commons? Obtenha a app para iniciar sessão com o seu Oxy ID.",

package/src/i18n/locales/zh-CN.json

@@ -108,6 +108,7 @@
     "loading": "正在加载账户...",
     "qrHeadline": "使用您的 Oxy 身份登录",
     "signInWithOxy": "使用 Oxy 登录",
+    "signUpWithOxy": "使用 Oxy 注册",
     "useIdentityOnDevice": "没有 Commons？改用此设备上的通行密钥",
     "getCommons": "获取 Commons",
     "commonsNotInstalled": "没有 Commons？获取应用以使用您的 Oxy ID 登录。",

package/src/index.ts

@@ -86,10 +86,6 @@ export type {
     ContactDiscoveryMatch,
     ContactDiscoveryResponse,
 } from './mixins/OxyServices.contacts';
-export type {
-    InitDeviceTransferResult,
-    DeviceTransferOutcome,
-} from './mixins/OxyServices.deviceTransfer';
 export type {
     BulkFollowEntry,
     BulkFollowResult,
@@ -234,7 +230,6 @@ export {
 export { buildUserDid } from './mixins/OxyServices.identity';
 export type {
     IdentityRecordType,
-    UnlinkableAuthMethodType,
     LinkAuthMethodResult,
     PublishRecordResult,
     VerifyRecordResult,
@@ -338,41 +333,55 @@ export {
 export type { AeadResult } from './crypto/aead';
 export { deriveSharedSecret } from './crypto/ecdh';
 
-// Web identity carrier — the same identity as Commons, sealed under a passkey's
-// PRF output (docs/superpowers/specs/2026-09-15-one-identity-two-carriers-design.md)
+// Web identity holder — the same root as Commons, sealed under a passkey's PRF
+// output; identity proofs; transfer to Commons (docs/adr/0024-one-oxy-account-root-holders.md)
 export {
     WEB_IDENTITY_PRF_INPUT,
     WebIdentityUnlockError,
+    WEB_IDENTITY_PRF_OUTPUT_LENGTH,
     addWrap,
-    buildIdentityActionMessage,
     deriveIdentityFromMnemonic,
+    deriveIdentityFromPrivateKey,
+    deriveIdentityFromRecoveryMaterial,
     deriveKeyEncryptionKey,
-    deriveTransferSas,
     generateDataKey,
     generateWebIdentity,
+    isUsablePrfOutput,
+    markWrapVerified,
+    normalizeMnemonic,
     openWebIdentity,
+    parseRecoveryMaterial,
     removeWrap,
     sealWebIdentity,
-    signIdentityAction,
     unlockWebIdentity,
     unwrapDataKey,
     wipeBytes,
-    wrapDataKey,
+    wipeOpenedIdentity,
+} from './crypto/webIdentityCarrier';
+export type {
+    OpenedMnemonicIdentity,
+    OpenedRawKeyIdentity,
+    OpenedWebIdentity,
+    WebIdentityRecoveryMaterial,
+    WebIdentityUnlockFailure,
+    WrapInput,
 } from './crypto/webIdentityCarrier';
-export type { OpenedWebIdentity, WebIdentityUnlockFailure } from './crypto/webIdentityCarrier';
+export { digestIdentityPayload, signIdentityProof } from './crypto/identityProof';
 export {
-    IDENTITY_MOVE_ACTIONS,
-    buildMoveMessage,
     buildMoveQrPayload,
+    createMoveCommitment,
     deriveMoveKey,
     deriveMoveSas,
+    digestMoveCiphertext,
     generateMoveEphemeralKeyPair,
     openMovedIdentity,
     parseMoveQrPayload,
     sealIdentityForMove,
-    signMoveAction,
+    signMoveReceipt,
+    verifyMoveCommitment,
     verifyMoveReceipt,
 } from './crypto/identityMove';
+export type { MoveReceiptClaims } from './crypto/identityMove';
 
 // ---------------------------------------------------------------------------
 // Devices
@@ -909,6 +918,8 @@ export type {
     OxyInferenceResponse,
     OxyGenerationReceipt,
     OxyResponsesRequest,
+    OxySpeechRequest,
+    OxySpeechResponse,
 } from './inference/OxyInferenceClient';
 
 export { runSessionColdBoot } from './boot/sessionColdBoot';

package/src/inference/OxyInferenceClient.ts

@@ -58,7 +58,9 @@ import type {
     InferenceFinishReason,
     InferenceMessage,
     InferenceRequestOutcome,
+    InferenceAudioMediaType,
     InferenceStreamEvent,
+    InferenceSpeechParameters,
     ModelCatalogueEntry,
     ResponseFormat,
     RoutingPolicyReference,
@@ -69,7 +71,13 @@ import type {
     UsageQuantity,
     UsageSource,
 } from '@oxy.so/contracts';
-import { INFERENCE_ERROR_CODES, inferenceStreamEventSchema, modelIdSchema } from '@oxy.so/contracts';
+import {
+    INFERENCE_ERROR_CODES,
+    MAX_INFERENCE_AUDIO_BYTES,
+    inferenceAudioMediaTypeSchema,
+    inferenceStreamEventSchema,
+    modelIdSchema,
+} from '@oxy.so/contracts';
 
 /** The base URL of the Oxy API, when a caller names none. */
 export const OXY_INFERENCE_BASE_URL = 'https://api.oxy.so';
@@ -138,6 +146,23 @@ export interface OxyResponsesRequest {
     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:
@@ -434,6 +459,57 @@ export class OxyInferenceClient {
         });
     }
 
+    /** Generate audio bytes through Oxy's authenticated inference edge. */
+    async speech(
+        request: OxySpeechRequest,
+        options: OxyInferenceRequestOptions = {},
+    ): Promise<OxySpeechResponse> {
+        const response = await this.#fetch(`${this.#baseURL}/v1/audio/speech`, {
+            method: 'POST',
+            headers: await this.#headers('audio/*', {
+                hasBody: true,
+                ...(options.idempotencyKey === undefined
+                    ? {}
+                    : { idempotencyKey: options.idempotencyKey }),
+                ...(options.delegatedUserId === undefined
+                    ? {}
+                    : { delegatedUserId: options.delegatedUserId }),
+            }),
+            body: JSON.stringify(request),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+        const requestId = response.headers.get('X-Oxy-Request-Id') ?? '';
+        if (!response.ok) {
+            throw toInferenceError(await response.json().catch(() => undefined), response.status, requestId);
+        }
+        const mediaType = inferenceAudioMediaTypeSchema.safeParse(mediaTypeOf(response));
+        if (!mediaType.success || !response.body) {
+            await cancelUnreadResponse(response);
+            throw protocolError('The inference API returned no supported audio body.', requestId);
+        }
+        const reader = response.body.getReader();
+        const chunks: Uint8Array[] = [];
+        let size = 0;
+        let completed = false;
+        try {
+            while (true) {
+                const next = await reader.read();
+                if (next.done) { completed = true; break; }
+                size += next.value.byteLength;
+                if (size > MAX_INFERENCE_AUDIO_BYTES) throw protocolError('The inference audio exceeds the response limit.', requestId);
+                chunks.push(next.value);
+            }
+        } finally {
+            if (!completed) await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
+        }
+        if (size === 0) throw protocolError('The inference API returned empty audio.', requestId);
+        const audio = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) { audio.set(chunk, offset); offset += chunk.byteLength; }
+        return { audio, mediaType: mediaType.data, requestId };
+    }
+
     /**
      * Stream one inference request from `POST /v1/responses`.
      *
@@ -481,11 +557,7 @@ export class OxyInferenceClient {
         }
 
         const requestId = response.headers.get('X-Oxy-Request-Id') ?? undefined;
-        const mediaType = response.headers
-            .get('Content-Type')
-            ?.split(';', 1)[0]
-            ?.trim()
-            .toLowerCase();
+        const mediaType = mediaTypeOf(response);
         if (mediaType !== 'text/event-stream') {
             await cancelUnreadResponse(response);
             throw protocolError(
@@ -607,7 +679,7 @@ export class OxyInferenceClient {
 
     /** Build the authenticated headers for one request, re-reading its bearer. */
     async #headers(
-        accept: 'application/json' | 'text/event-stream',
+        accept: 'application/json' | 'text/event-stream' | 'audio/*',
         options: {
             hasBody: boolean;
             idempotencyKey?: string;
@@ -694,6 +766,11 @@ function protocolError(message: string, requestId?: string): OxyInferenceProtoco
     return new OxyInferenceProtocolError(message, requestId);
 }
 
+/** The bare, lowercased media type of a response's `Content-Type`, if any. */
+function mediaTypeOf(response: Response): string | undefined {
+    return response.headers.get('Content-Type')?.split(';', 1)[0]?.trim().toLowerCase();
+}
+
 /** Cancel a nominally successful response whose stream contract is unreadable. */
 async function cancelUnreadResponse(response: Response): Promise<void> {
     await response.body?.cancel().catch(() => undefined);

package/src/inference/__tests__/OxyInferenceClient.test.ts

@@ -832,3 +832,51 @@ describe('OxyInferenceClient', () => {
         expect(calls[0].url).toBe('http://test.invalid/v1/models');
     });
 });
+
+
+describe('speech', () => {
+    it('preserves audio bytes, exact profile and delegated user with the service credential', async () => {
+        const bytes = new Uint8Array([73, 68, 51, 0, 255, 4]);
+        const transport = jest.fn(async () => new Response(bytes, { headers: {
+            'Content-Type': 'audio/mpeg', 'X-Oxy-Request-Id': 'req_speech',
+        } }));
+        const client = new OxyInferenceClient({ credential: async () => 'service-test', fetch: transport });
+        const input = { routingProfileId: 'opaque-reviewed-id', input: 'Hola 👋', voice: 'female', speed: 1.15 };
+        const result = await client.speech(input, { delegatedUserId: 'user_test', idempotencyKey: 'speech_test' });
+        expect(result).toEqual({ audio: bytes, mediaType: 'audio/mpeg', requestId: 'req_speech' });
+        const [url, init] = (transport.mock.calls as unknown as Array<[string, RequestInit]>)[0];
+        expect(url).toBe('https://api.oxy.so/v1/audio/speech');
+        expect(JSON.parse(String(init.body))).toEqual(input);
+        const headers = new Headers(init.headers);
+        expect(headers.get('Authorization')).toBe('Bearer service-test');
+        expect(headers.get('X-Oxy-User-Id')).toBe('user_test');
+        expect(headers.get('Idempotency-Key')).toBe('speech_test');
+    });
+    it('preserves retryable refusal metadata without retrying a paid request', async () => {
+        const transport = jest.fn(async () => new Response(JSON.stringify({ schemaVersion: 1,
+            code: 'rate_limited', message: 'Capacity unavailable', requestId: 'req_throttled',
+            retryable: true, retryAfterMs: 1500 }), { status: 429 }));
+        const client = new OxyInferenceClient({ credential: 'test', fetch: transport });
+        await expect(client.speech({ model: 'xai/tts', input: 'Hola', voice: 'female' }))
+            .rejects.toMatchObject({ code: 'rate_limited', requestId: 'req_throttled', retryAfterMs: 1500 });
+        expect(transport).toHaveBeenCalledTimes(1);
+    });
+    it.each([
+        { body: '', type: 'audio/mpeg' }, { body: '<html>unavailable</html>', type: 'text/html' },
+        { body: '{}', type: 'application/json' },
+    ])('refuses successful HTTP responses without audio: %p', async ({ body, type }) => {
+        const client = new OxyInferenceClient({ credential: 'test', fetch: async () =>
+            new Response(body, { headers: { 'Content-Type': type } }) });
+        await expect(client.speech({ model: 'xai/tts', input: 'Hola', voice: 'female' }))
+            .rejects.toBeInstanceOf(OxyInferenceProtocolError);
+    });
+    it('bounds streamed binary output and cancels the remaining body', async () => {
+        const cancelled = jest.fn();
+        const client = new OxyInferenceClient({ credential: 'test', fetch: async () => new Response(
+            new ReadableStream({ start(controller) { controller.enqueue(new Uint8Array(20 * 1024 * 1024 + 1)); }, cancel: cancelled }),
+            { headers: { 'Content-Type': 'audio/mpeg' } }) });
+        await expect(client.speech({ model: 'xai/tts', input: 'Hola', voice: 'female' }))
+            .rejects.toBeInstanceOf(OxyInferenceProtocolError);
+        expect(cancelled).toHaveBeenCalledTimes(1);
+    });
+});

package/src/mixins/OxyServices.auth.ts

@@ -9,7 +9,7 @@ import type {
   LoginResult,
   CommonsDenyReason,
 } from '@oxy.so/contracts';
-import { loginResultSchema, safeParseContract } from '@oxy.so/contracts';
+import { loginResultSchema, safeParseContract, 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';
@@ -546,6 +546,24 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       const secret = apiSecret || this._serviceApiSecret;
 
       if (!key || !secret) {
+        /**
+         * No credential configured — so prove what this process IS instead
+         * (ADR 0026).
+         *
+         * This is what lets an official service drop its api key and secret
+         * WITHOUT a code change: remove the two environment variables, and the
+         * next token comes from the workload path. It is deliberately the
+         * fallback rather than the preference, so a deployment that still has a
+         * credential keeps using it and the migration is one service at a time.
+         *
+         * A process with no credential AND no attestation still gets the
+         * original error: "nothing to authenticate with" is the truth there, and
+         * a local checkout must not be told to go looking for a container
+         * credentials endpoint that is not there.
+         */
+        if (await this._canUseWorkloadIdentity()) {
+          return this._getWorkloadServiceToken();
+        }
         throw new Error('Service credentials not provided. Call configureServiceAuth() or pass apiKey and apiSecret.');
       }
 
@@ -625,6 +643,81 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
+    /**
+     * 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
+     */
+    async _canUseWorkloadIdentity(): Promise<boolean> {
+      if (typeof process === 'undefined' || !process.versions?.node) return false;
+      try {
+        const { canAttestWorkloadIdentity } = await import('../server/workloadIdentity');
+        return canAttestWorkloadIdentity();
+      } catch {
+        // A bundler that dropped the server subpath, or a runtime without it.
+        // "We cannot attest here" is the correct reading, and the caller falls
+        // back to the credential error it would have thrown anyway.
+        return false;
+      }
+    }
+
+    /**
+     * 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
+     */
+    async _getWorkloadServiceToken(): Promise<string> {
+      const cacheKey = 'workload-identity';
+      const entry = this._serviceTokenCache.get(cacheKey);
+      const now = Date.now();
+      if (entry?.token && entry.expiresAt > now + 60_000) return entry.token;
+      if (entry?.pending) return entry.pending;
+
+      const { requestWorkloadServiceToken } = await import('../server/workloadIdentity');
+      const seeded = entry ?? {
+        token: '',
+        expiresAt: 0,
+        secretBuf: Buffer.alloc(0),
+        pending: null,
+        apiKey: cacheKey,
+      };
+      this._serviceTokenCache.set(cacheKey, seeded);
+
+      const pending = (async () => {
+        const granted = await requestWorkloadServiceToken({ baseUrl: this.getBaseURL() });
+        const current = this._serviceTokenCache.get(cacheKey);
+        if (current) {
+          current.token = granted.token;
+          current.expiresAt = Date.now() + granted.expiresIn * 1000;
+        }
+        return granted.token;
+      })();
+      seeded.pending = pending;
+
+      try {
+        return await pending;
+      } catch (error) {
+        // Never keep an entry that never held a token: the next caller must try
+        // again rather than inherit a failure.
+        const failed = this._serviceTokenCache.get(cacheKey);
+        if (failed?.pending === pending && !failed.token) this._serviceTokenCache.delete(cacheKey);
+        throw error;
+      } finally {
+        const settled = this._serviceTokenCache.get(cacheKey);
+        if (settled?.pending === pending) settled.pending = null;
+      }
+    }
+
     /**
      * Perform the actual /auth/service-token request and cache the result.
      * Separated so getServiceToken() can deduplicate concurrent calls.
@@ -1643,6 +1736,12 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         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 } | LoginResult> {
       try {

package/src/mixins/OxyServices.identity.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,12 +19,13 @@
  * 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,
+  IdentityRootStatus,
   DidDocument,
   DomainVerificationInstructions,
   ExportBundle,
@@ -58,13 +59,7 @@ const OXY_IDENTITY_APEX = 'oxy.so';
  */
 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;
@@ -224,62 +219,15 @@ export function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base:
     }
 
     /**
-     * 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.
+     * 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.
      */
-    async linkIdentityKey(): Promise<LinkAuthMethodResult> {
+    async getIdentityRootStatus(): Promise<IdentityRootStatus> {
       try {
-        const userId = this.getCurrentUserId();
-        if (!userId) {
-          throw new Error('No authenticated user — sign in before linking an identity key.');
-        }
-        const publicKey = await KeyManager.getPublicKey();
-        if (!publicKey) {
-          throw new Error('No identity found on this device. Create or import an identity first.');
-        }
-
-        const timestamp = Date.now();
-        // The signed message MUST match the server's reconstruction byte-for-byte:
-        // JSON.stringify with this exact key order (action, userId, timestamp).
-        const message = JSON.stringify({ action: 'link_identity', userId, timestamp });
-        const signature = await SignatureService.sign(message);
-
-        const result = await this.makeRequest<LinkAuthMethodResult>(
-          'POST',
-          '/auth/link',
-          { type: 'identity', publicKey, signature, timestamp },
-          { cache: false },
-        );
-        this._invalidateIdentityCaches(userId);
-        return result;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * 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.
-     */
-    async unlinkAuthMethod(type: UnlinkableAuthMethodType): Promise<LinkAuthMethodResult> {
-      try {
-        const result = await this.makeRequest<LinkAuthMethodResult>(
-          'DELETE',
-          `/auth/link/${encodeURIComponent(type)}`,
-          undefined,
-          { cache: false },
-        );
-        this._invalidateIdentityCaches(this.getCurrentUserId());
-        return result;
+        return await this.makeRequest<IdentityRootStatus>('GET', '/identity/root-status', undefined, { cache: false });
       } catch (error) {
         throw this.handleError(error);
       }
@@ -288,10 +236,12 @@ export function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base:
     /**
      * 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/src/mixins/OxyServices.utility.ts

@@ -1178,6 +1178,8 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      */
     serviceAuth(options: {
       debug?: boolean;
+      /** Observe refusals on the service lane; forwarded straight to `auth()`. */
+      onRefusal?: (refusal: OxyAuthRefusal) => void;
       /** @deprecated Oxy-API-only HS256 transition; external verifiers use JWKS. */
       jwtSecret?: string;
       serviceTokenJwksUrl?: string;