@oxy.so/core 1.16.0 → 1.18.1

package/dist/esm/mixins/OxyServices.auth.js

@@ -1,4 +1,4 @@
-import { loginResultSchema, safeParseContract } from '@oxy.so/contracts';
+import { emailVerificationConfirmResponseSchema, emailVerificationStartResponseSchema, loginResultSchema, safeParseContract, } from '@oxy.so/contracts';
 export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from '../utils/commonsApproval.js';
 import { OxyAuthenticationError } from '../OxyServices.errors.js';
 import { KeyManager } from '../crypto/keyManager.js';
@@ -85,6 +85,11 @@ export class ServiceCredentialMismatchError extends Error {
         this.name = 'ServiceCredentialMismatchError';
     }
 }
+/**
+ * How long a failed service-token mint sends session-less requests anonymous
+ * before the next attempt, under `serviceIdentity: 'when-anonymous'`.
+ */
+export const ANONYMOUS_SERVICE_TOKEN_RETRY_MS = 30000;
 export function OxyServicesAuthMixin(Base) {
     return class extends Base {
         constructor(...args) {
@@ -111,6 +116,56 @@ export function OxyServicesAuthMixin(Base) {
             this._serviceApiKey = null;
             /** @internal Raw apiSecret stored by configureServiceAuth() for use by getServiceToken() */
             this._serviceApiSecret = null;
+            /**
+             * Before this instant, a request without a user session does not try to
+             * mint a service token and goes out anonymous. Set after a failed mint; see
+             * {@link _serviceTokenForAnonymousRequest}.
+             *
+             * @internal
+             */
+            this._anonymousServiceTokenRetryAt = 0;
+            if (this.config.serviceIdentity === 'when-anonymous') {
+                this.httpService.setAnonymousAuthProvider(() => this._serviceTokenForAnonymousRequest());
+            }
+        }
+        /**
+         * The bearer for a request with no user session, under `serviceIdentity:
+         * 'when-anonymous'`: this process's service token, or `null` to send the
+         * request anonymous as before.
+         *
+         * `null`, never a throw, whenever there is no token to offer:
+         * - no key pair and no attestable workload (a local checkout) — asking
+         *   costs nothing and there is nothing to ask for;
+         * - the mint failed. The request still goes out, anonymous, and so does
+         *   every request for the next {@link ANONYMOUS_SERVICE_TOKEN_RETRY_MS}, so
+         *   an Oxy that is refusing attestation (seen for ~2.5 minutes after a
+         *   deploy on 2026-09-25) is asked once per window rather than once per
+         *   read, and no read waits on a mint that just failed.
+         *
+         * The token itself comes from {@link getServiceToken}: cached for its
+         * lifetime and single-flight, so concurrent reads share one mint.
+         *
+         * @internal
+         */
+        async _serviceTokenForAnonymousRequest() {
+            if (Date.now() < this._anonymousServiceTokenRetryAt)
+                return null;
+            const hasKeyPair = Boolean(this._serviceApiKey && this._serviceApiSecret);
+            if (!hasKeyPair && !(await this._canUseWorkloadIdentity()))
+                return null;
+            try {
+                return await this.getServiceToken();
+            }
+            catch (error) {
+                this._anonymousServiceTokenRetryAt = Date.now() + ANONYMOUS_SERVICE_TOKEN_RETRY_MS;
+                logger.warn('[oxy.auth] No service token for a request without a session; sending it anonymous', {
+                    component: 'auth',
+                    method: '_serviceTokenForAnonymousRequest',
+                    retryInMs: ANONYMOUS_SERVICE_TOKEN_RETRY_MS,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return null;
+            }
         }
         /**
          * Hash an apiKey into a stable Map cache key. Uses Node's SHA-256 — service
@@ -1126,12 +1181,40 @@ export function OxyServicesAuthMixin(Base) {
             }
         }
         /**
-         * Check email availability
+         * Send a 6-digit code to an email (ADR 0029 D3): the recovery email of a
+         * new passkey account (`purpose: 'signup'`), or — named by username or
+         * email — the recovery email of an account being recovered
+         * (`purpose: 'recovery'`). The answer is the same whether or not an
+         * account exists; nothing is revealed about who has one.
          */
-        async checkEmailAvailability(email) {
+        async startEmailVerification(request) {
             try {
-                // Public availability lookup (pre-session) — skip the bearer preflight.
-                return await this.makeRequest('GET', `/auth/check-email/${email}`, undefined, { cache: false, skipAuth: true });
+                const res = await this.makeRequest('POST', '/auth/email/verify/start', request, {
+                    cache: false,
+                    skipAuth: true,
+                });
+                const parsed = safeParseContract(emailVerificationStartResponseSchema, res);
+                if (!parsed)
+                    throw new Error('auth/email/verify/start returned an unexpected response shape');
+                return parsed;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Confirm the code {@link startEmailVerification} sent. Resolves to a
+         * short-lived one-use ticket: a sign-up passes it (with the email) to
+         * {@link webauthnRegisterVerify}; a recovery passes it as `recoveryTicket`
+         * to {@link webauthnRegisterOptions} and {@link webauthnRegisterVerify}.
+         */
+        async confirmEmailVerification(verificationId, code) {
+            try {
+                const res = await this.makeRequest('POST', '/auth/email/verify/confirm', { verificationId, code }, { cache: false, skipAuth: true });
+                const parsed = safeParseContract(emailVerificationConfirmResponseSchema, res);
+                if (!parsed)
+                    throw new Error('auth/email/verify/confirm returned an unexpected response shape');
+                return parsed;
             }
             catch (error) {
                 throw this.handleError(error);
@@ -1142,15 +1225,20 @@ export function OxyServicesAuthMixin(Base) {
          * `PublicKeyCredentialCreationOptions` the browser's `navigator.credentials
          * .create()` (or `@simplewebauthn/browser`'s `startRegistration`) needs.
          *
-         * With a bearer token planted this links a passkey to the signed-in account
-         * (`username` ignored); without one it is a prospective signup and `username`
-         * is the desired handle. The returned options are OPAQUE — Oxy does not own
-         * their shape (the browser / `@simplewebauthn` does), so they pass through
-         * as `unknown` for the caller to hand straight to the ceremony.
+         * With a bearer token planted this adds a passkey to the signed-in account.
+         * Without one, `username` is a prospective sign-up's handle, and
+         * `recoveryTicket` a recovery's new passkey for the account it names. The
+         * returned options are OPAQUE — Oxy does not own their shape (the browser /
+         * `@simplewebauthn` does), so they pass through as `unknown` for the caller
+         * to hand straight to the ceremony.
          */
-        async webauthnRegisterOptions(username) {
+        async webauthnRegisterOptions(request = {}) {
+            const signedOut = request.username !== undefined || request.recoveryTicket !== undefined;
             try {
-                return await this.makeRequest('POST', '/auth/webauthn/register/options', { ...(username !== undefined ? { username } : {}) }, { cache: false, ...(username !== undefined ? { skipAuth: true } : {}) });
+                return await this.makeRequest('POST', '/auth/webauthn/register/options', {
+                    ...(request.username !== undefined ? { username: request.username } : {}),
+                    ...(request.recoveryTicket !== undefined ? { recoveryTicket: request.recoveryTicket } : {}),
+                }, { cache: false, ...(signedOut ? { skipAuth: true } : {}) });
             }
             catch (error) {
                 throw this.handleError(error);
@@ -1161,17 +1249,22 @@ export function OxyServicesAuthMixin(Base) {
          * browser `RegistrationResponseJSON` (`response`) alongside the Oxy envelope
          * (desired `username` for signup + the device-session naming fields).
          *
-         * Two server branches, disambiguated by the response shape:
-         *  - **Signup** (no bearer): the account is created and a session minted —
-         *    the response carries `sessionId`, is the SAME {@link LoginResult}
-         *    contract as `POST /auth/verify`, and its access token is planted here.
+         * Server branches, disambiguated by the response shape:
+         *  - **Sign-up** (no bearer; `username`, `email`, `emailTicket`) and
+         *    **recovery** (no bearer; `recoveryTicket`): the account is created, or
+         *    gains the passkey, and a session is minted — the response carries
+         *    `sessionId`, is the SAME {@link LoginResult} contract as
+         *    `POST /auth/verify`, and its access token is planted here.
          *  - **Link** (bearer present): the passkey is attached to the signed-in
          *    account and the server returns `{ success, message }` with no session,
          *    which is returned verbatim (no token planting).
          */
         async webauthnRegisterVerify(response, envelope = {}) {
             try {
-                const res = await this.makeRequest('POST', '/auth/webauthn/register/verify', { response, ...envelope }, { cache: false, ...(envelope.username !== undefined ? { skipAuth: true } : {}) });
+                const res = await this.makeRequest('POST', '/auth/webauthn/register/verify', { response, ...envelope }, {
+                    cache: false,
+                    ...(envelope.username !== undefined || envelope.recoveryTicket !== undefined ? { skipAuth: true } : {}),
+                });
                 if (res && typeof res === 'object') {
                     const record = res;
                     // Signup branch: mints a session (LoginSessionResult, carries

package/dist/esm/mixins/OxyServices.identity.js

@@ -1,5 +1,33 @@
+/**
+ * Identity Methods Mixin (self-sovereign identity layer)
+ *
+ * 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 (`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.
+ *  - The signed data-export ("credible exit") bundle.
+ *  - Verified-domain badges (prove ownership of `nate.com`).
+ *
+ * Wire shapes come from `@oxy.so/contracts` (`DidDocument`,
+ * `SignedRecordEnvelope`, `AuthMethodsResponse`, `VerifiedDomain`,
+ * `DomainVerificationInstructions`, `ExportBundle`) — the single source of truth
+ * 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 `signRecord` and `publishRecord` require an
+ * on-device identity and throw on web (where `KeyManager.getPublicKey()` is
+ * always `null`).
+ */
+import { IDENTITY_PROOF_ACTIONS, identityLinkCreateResponseSchema, identityLinkStateSchema, safeParseContract, } from '@oxy.so/contracts';
 import { signMessage } from '@oxy.so/protocol';
 import { KeyManager } from '../crypto/keyManager.js';
+import { deriveIdentityLinkCode } from '../crypto/identityLink.js';
+import { signIdentityProof } from '../crypto/identityProof.js';
 import { SignatureService } from '../crypto/signatureService.js';
 import { RecoveryPhraseService } from '../crypto/recoveryPhrase.js';
 import { isWeb } from '../utils/platform.js';
@@ -71,11 +99,9 @@ export function OxyServicesIdentityMixin(Base) {
             }
         }
         /**
-         * 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.
+         * How the signed-in account is kept (ADR 0029 D3): whether Commons' root is
+         * linked (self-custody), or the recovery email of a passkey account. Any
+         * first-party surface may read it to recommend linking Commons.
          */
         async getIdentityRootStatus() {
             try {
@@ -85,15 +111,109 @@ export function OxyServicesIdentityMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Open a request to link Commons to the signed-in passkey account (ADR 0029
+         * D3). auth.oxy.so shows its `qrPayload`; Commons scans it and signs with
+         * {@link signIdentityLink}.
+         */
+        async createIdentityLink() {
+            try {
+                const res = await this.makeRequest('POST', '/identity/link', undefined, { cache: false });
+                const parsed = safeParseContract(identityLinkCreateResponseSchema, res);
+                if (!parsed)
+                    throw new Error('identity/link returned an unexpected response shape');
+                return parsed;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Where a link request stands. Both devices poll it; it needs no session. */
+        async getIdentityLink(linkId) {
+            try {
+                const res = await this.makeRequest('GET', `/identity/link/${encodeURIComponent(linkId)}`, undefined, {
+                    cache: false,
+                    skipAuth: true,
+                });
+                const parsed = safeParseContract(identityLinkStateSchema, res);
+                if (!parsed)
+                    throw new Error('identity/link returned an unexpected response shape');
+                return parsed;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Commons' half: sign the scanned request's `link_identity` proof with THIS
+         * device's identity key and post it. NATIVE-ONLY (the key lives in native
+         * secure storage). Resolves to the key and the 6-digit code auth.oxy.so will
+         * show for it, for the person to compare.
+         */
+        async signIdentityLink(linkId, challenge) {
+            try {
+                const [privateKey, publicKey] = await Promise.all([KeyManager.getPrivateKey(), KeyManager.getPublicKey()]);
+                if (!privateKey || !publicKey) {
+                    throw new Error('No identity on this device to link');
+                }
+                const root = publicKey.trim().toLowerCase();
+                const state = await this.getIdentityLink(linkId);
+                const proof = await signIdentityProof({ privateKey, publicKey: root }, {
+                    action: IDENTITY_PROOF_ACTIONS.link,
+                    subject: state.userId,
+                    actor: state.userId,
+                    rootPublicKey: root,
+                    payloadDigest: null,
+                    expectedRevision: null,
+                    audience: state.audience,
+                    challenge,
+                    expiresAt: state.expiresAt,
+                });
+                await this.makeRequest('POST', `/identity/link/${encodeURIComponent(linkId)}/proof`, { publicKey: root, proof }, { cache: false, skipAuth: true });
+                return { publicKey: root, code: deriveIdentityLinkCode(linkId, root), username: state.username };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** WebAuthn request options over the account's passkeys, whose challenge is the link's. Opaque. */
+        async getIdentityLinkAssertionOptions(linkId, challenge) {
+            try {
+                return await this.makeRequest('POST', `/identity/link/${encodeURIComponent(linkId)}/options`, { challenge }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * auth.oxy.so's half: the passkey assertion over the link's challenge. The
+         * account gains Commons' root and loses its recovery email.
+         */
+        async completeIdentityLink(linkId, assertion) {
+            try {
+                const result = await this.makeRequest('POST', `/identity/link/${encodeURIComponent(linkId)}/complete`, { assertion }, { cache: false });
+                this._invalidateIdentityCaches(this.getCurrentUserId());
+                return result;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Withdraw a link request that has not completed. */
+        async cancelIdentityLink(linkId) {
+            try {
+                await this.makeRequest('DELETE', `/identity/link/${encodeURIComponent(linkId)}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
         /**
          * Remove ONE passkey (WebAuthn credential) from the current account.
          *
          * 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/esm/mixins/OxyServices.user.js

@@ -532,6 +532,35 @@ export function OxyServicesUserMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * WebAuthn request options to delete a PASSKEY account (ADR 0029 D3): its own
+         * passkeys, user verification required, and a challenge bound to it. Opaque —
+         * hand them to the browser's authentication ceremony, on auth.oxy.so. An
+         * account with a Commons key deletes with {@link deleteAccount} instead.
+         */
+        async getAccountDeletionOptions() {
+            try {
+                return await this.makeRequest('POST', '/users/me/delete/options', undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Delete a PASSKEY account permanently, with an assertion by one of its
+         * passkeys over {@link getAccountDeletionOptions}' challenge.
+         *
+         * @param confirmText - Must equal the user's username (verified server-side)
+         * @param assertion - The ceremony's opaque `AuthenticationResponseJSON`
+         */
+        async deleteAccountWithPasskey(confirmText, assertion) {
+            try {
+                return await this.makeRequest('DELETE', '/users/me', { confirmText, assertion }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
         /**
          * Invalidate every cached read a follow/unfollow write invalidates.
          *
@@ -841,11 +870,13 @@ export function OxyServicesUserMixin(Base) {
             }
         }
         /**
-         * Get notifications
+         * One page of the signed-in user's Oxy notifications, newest first
+         * (`GET /notifications`), with the unread count across all pages.
          */
-        async getNotifications() {
+        async getNotifications(params = {}) {
+            const query = buildQueryParams({ page: params.page, limit: params.limit });
             return this.withAuthRetry(async () => {
-                return await this.makeRequest('GET', '/notifications', undefined, {
+                return await this.makeRequest('GET', '/notifications', query, {
                     cache: false, // Don't cache notifications - always get fresh data
                 });
             }, 'getNotifications');
@@ -858,7 +889,7 @@ export function OxyServicesUserMixin(Base) {
                 const res = await this.makeRequest('GET', '/notifications/unread-count', undefined, {
                     cache: false, // Don't cache unread count - always get fresh data
                 });
-                return res.count;
+                return res.unreadCount;
             }
             catch (error) {
                 throw this.handleError(error);
@@ -873,18 +904,22 @@ export function OxyServicesUserMixin(Base) {
          */
         async createNotification(data) {
             try {
-                return await this.makeRequest('POST', '/notifications', data, { cache: false });
+                const res = await this.makeRequest('POST', '/notifications', data, { cache: false });
+                return res.notification;
             }
             catch (error) {
                 throw this.handleError(error);
             }
         }
         /**
-         * Mark notification as read
+         * Mark one of the signed-in user's notifications read and return it as
+         * stored. Scoped to the recipient server-side, so it is also the
+         * authoritative read of a notification by id: a foreign or unknown id 404s.
          */
         async markNotificationAsRead(notificationId) {
             try {
-                await this.makeRequest('PUT', `/notifications/${notificationId}/read`, undefined, { cache: false });
+                const res = await this.makeRequest('PUT', `/notifications/${encodeURIComponent(notificationId)}/read`, undefined, { cache: false });
+                return res.notification;
             }
             catch (error) {
                 throw this.handleError(error);

package/dist/esm/utils/authWebUrl.js

@@ -15,10 +15,9 @@
  */
 export const CENTRAL_IDP_APEX = 'oxy.so';
 /**
- * The IdP's origin, `auth.oxy.so` — the OAuth authorize/consent surface AND the
- * web identity carrier: where a person signs in or creates an account with a
- * passkey from another origin's popup, and the one origin that may create,
- * open, recover or move their self-custody identity (one identity, two
- * carriers). Apps open it; they never handle the identity themselves.
+ * The IdP's origin, `auth.oxy.so` — the OAuth authorize/consent surface and the
+ * one origin that asserts Oxy passkeys: where a person signs in, creates,
+ * recovers or deletes a web account, in the window an app opens (ADR 0029).
+ * Apps open it; they never run the passkey themselves.
  */
 export const AUTH_WEB_ORIGIN = `https://auth.${CENTRAL_IDP_APEX}`;