@oxy.so/core 1.16.0 → 1.18.1

package/dist/types/HttpService.d.ts

@@ -17,6 +17,11 @@ import type { DeviceSecretMintOutcome } from './session/refresh';
 export type AuthRefreshReason = 'preflight' | 'response-401';
 export type AuthRefreshHandler = (reason: AuthRefreshReason) => Promise<string | null>;
 export type AccessTokenProvider = () => string | null;
+/**
+ * Supplies a bearer for a request made while this client holds NO user session
+ * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
+ */
+export type AnonymousAuthProvider = () => Promise<string | null>;
 /**
  * A low-level authenticated request whose response body remains unread.
  *
@@ -162,6 +167,7 @@ export declare class HttpService {
     private noFresherTokenThan;
     private authRefreshHandler;
     private accessTokenProvider;
+    private anonymousAuthProvider;
     private deviceSecretMintInFlight;
     /**
      * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -324,6 +330,13 @@ export declare class HttpService {
      * Get auth header with automatic token refresh
      */
     private getAuthHeader;
+    /**
+     * The bearer for a request that has no user session behind it, from the
+     * {@link AnonymousAuthProvider} if one is installed. Never throws: a provider
+     * that fails sends the request anonymous, exactly as it went before any
+     * provider existed.
+     */
+    private getAnonymousAuthHeader;
     refreshAccessToken(reason: AuthRefreshReason): Promise<string | null>;
     /**
      * Report that the refresh/mint endpoint answered 429 Too Many Requests, so the
@@ -442,6 +455,14 @@ export declare class HttpService {
     hasSessionEnded(): boolean;
     setAuthRefreshHandler(handler: AuthRefreshHandler | null): void;
     setAccessTokenProvider(provider: AccessTokenProvider | null): void;
+    /**
+     * Authenticate requests that carry no user session with the bearer this
+     * provider returns — in practice a backend's own service token (see
+     * `OxyConfig.serviceIdentity`). A user session always wins: the provider is
+     * consulted only when there is no access token, and never for `skipAuth`
+     * requests. `null` removes it.
+     */
+    setAnonymousAuthProvider(provider: AnonymousAuthProvider | null): void;
     clearTokens(): void;
     /**
      * Subscribe to access-token changes on this instance.

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

@@ -0,0 +1,8 @@
+/**
+ * The code both screens show while Commons is being linked to a passkey
+ * account (ADR 0029 D3): 6 digits derived from the link request and the key
+ * Commons signed with. auth.oxy.so derives it from the key the API relayed,
+ * Commons from its own; the person checks they match before the passkey is
+ * asserted, so a photographed QR cannot slip another key in.
+ */
+export declare function deriveIdentityLinkCode(linkId: string, publicKey: string): string;

package/dist/types/index.d.ts

@@ -72,14 +72,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, 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 { deriveIdentityLinkCode } from './crypto/identityLink';
 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';
+export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, NotificationActor, NotificationPage, 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';
 export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
 export { TopicType, TopicSource } from './models/Topic';
 export type { TopicData, TopicTranslation, TopicListResult } from './models/Topic';

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

@@ -5,7 +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 EmailVerificationConfirmResponse, type EmailVerificationStartRequest, type EmailVerificationStartResponse } from '@oxy.so/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
@@ -322,6 +322,11 @@ interface ServiceTokenCacheEntry {
 export declare class ServiceCredentialMismatchError extends Error {
     constructor();
 }
+/**
+ * How long a failed service-token mint sends session-less requests anonymous
+ * before the next attempt, under `serviceIdentity: 'when-anonymous'`.
+ */
+export declare const ANONYMOUS_SERVICE_TOKEN_RETRY_MS = 30000;
 export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -346,6 +351,34 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         _serviceApiKey: string | null;
         /** @internal Raw apiSecret stored by configureServiceAuth() for use by getServiceToken() */
         _serviceApiSecret: string | 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
+         */
+        _anonymousServiceTokenRetryAt: number;
+        /**
+         * 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
+         */
+        _serviceTokenForAnonymousRequest(): Promise<string | null>;
         /**
          * Hash an apiKey into a stable Map cache key. Uses Node's SHA-256 — service
          * tokens are only ever issued by a Node host (the SDK on web/RN never has
@@ -790,50 +823,60 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             message: string;
         }>;
         /**
-         * 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.
          */
-        checkEmailAvailability(email: string): Promise<{
-            available: boolean;
-            message: string;
-        }>;
+        startEmailVerification(request: EmailVerificationStartRequest): Promise<EmailVerificationStartResponse>;
+        /**
+         * 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}.
+         */
+        confirmEmailVerification(verificationId: string, code: string): Promise<EmailVerificationConfirmResponse>;
         /**
          * Begin a WebAuthn / passkey REGISTRATION ceremony. Requests the
          * `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.
          */
-        webauthnRegisterOptions(username?: string): Promise<unknown>;
+        webauthnRegisterOptions(request?: {
+            username?: string;
+            recoveryTicket?: string;
+        }): Promise<unknown>;
         /**
          * Finish a WebAuthn / passkey REGISTRATION ceremony. Forwards the opaque
          * 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).
          */
         webauthnRegisterVerify(response: unknown, envelope?: {
             username?: string;
+            /** Sign-up: the recovery email, confirmed with `emailTicket`. */
+            email?: string;
+            emailTicket?: string;
+            /** Recovery: the ticket {@link confirmEmailVerification} returned. */
+            recoveryTicket?: 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

@@ -1,29 +1,4 @@
-/**
- * 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 type { AuthMethodsResponse, IdentityRootStatus, DidDocument, DomainVerificationInstructions, ExportBundle, OxySignedRecordType, SignedRecordEnvelope, VerifiedDomain } from '@oxy.so/contracts';
+import type { AuthMethodsResponse, IdentityLinkCreateResponse, IdentityLinkState, IdentityRootStatus, DidDocument, DomainVerificationInstructions, ExportBundle, OxySignedRecordType, SignedRecordEnvelope, VerifiedDomain } from '@oxy.so/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PendingIdentityResult } from '../crypto/recoveryPhrase';
 /**
@@ -140,22 +115,47 @@ export declare function OxyServicesIdentityMixin<T extends typeof OxyServicesBas
          */
         listAuthMethods(): Promise<AuthMethodsResponse>;
         /**
-         * 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.
          */
         getIdentityRootStatus(): Promise<IdentityRootStatus>;
+        /**
+         * 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}.
+         */
+        createIdentityLink(): Promise<IdentityLinkCreateResponse>;
+        /** Where a link request stands. Both devices poll it; it needs no session. */
+        getIdentityLink(linkId: string): Promise<IdentityLinkState>;
+        /**
+         * 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.
+         */
+        signIdentityLink(linkId: string, challenge: string): Promise<{
+            publicKey: string;
+            code: string;
+            username: string | null;
+        }>;
+        /** WebAuthn request options over the account's passkeys, whose challenge is the link's. Opaque. */
+        getIdentityLinkAssertionOptions(linkId: string, challenge: string): Promise<unknown>;
+        /**
+         * auth.oxy.so's half: the passkey assertion over the link's challenge. The
+         * account gains Commons' root and loses its recovery email.
+         */
+        completeIdentityLink(linkId: string, assertion: unknown): Promise<{
+            success: true;
+        }>;
+        /** Withdraw a link request that has not completed. */
+        cancelIdentityLink(linkId: string): Promise<void>;
         /**
          * 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/types/mixins/OxyServices.user.d.ts

@@ -2,7 +2,7 @@
  * User Management Methods Mixin
  */
 import type { CreateOxyNotificationRequest } from '@oxy.so/contracts';
-import type { User, Notification, NotificationPreferences, UserPreferences, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
+import type { User, Notification, NotificationPage, NotificationPreferences, UserPreferences, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
 import type { UserNameResponse, UserProfileUpdate, RecommendationRequest, RecommendationItem, ThemePreference } from '@oxy.so/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PaginationParams, type FollowGraphParams } from '../utils/apiUtils';
@@ -350,6 +350,23 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         deleteAccount(confirmText: string): Promise<{
             message: string;
         }>;
+        /**
+         * 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.
+         */
+        getAccountDeletionOptions(): Promise<unknown>;
+        /**
+         * 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`
+         */
+        deleteAccountWithPasskey(confirmText: string, assertion: unknown): Promise<{
+            message: string;
+        }>;
         /**
          * Invalidate every cached read a follow/unfollow write invalidates.
          *
@@ -497,9 +514,13 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          */
         getViewerGraph(): Promise<ViewerGraph>;
         /**
-         * Get notifications
+         * One page of the signed-in user's Oxy notifications, newest first
+         * (`GET /notifications`), with the unread count across all pages.
          */
-        getNotifications(): Promise<Notification[]>;
+        getNotifications(params?: {
+            page?: number;
+            limit?: number;
+        }): Promise<NotificationPage>;
         /**
          * Get unread notification count
          */
@@ -511,11 +532,13 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * from an Oxy service about the recipient's own account, with the recipient
          * as actor and their profile as the entity.
          */
-        createNotification(data: CreateOxyNotificationRequest | Partial<Notification>): Promise<Notification>;
+        createNotification(data: CreateOxyNotificationRequest): Promise<Notification>;
         /**
-         * 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.
          */
-        markNotificationAsRead(notificationId: string): Promise<void>;
+        markNotificationAsRead(notificationId: string): Promise<Notification>;
         /**
          * Mark all notifications as read
          */

package/dist/types/models/interfaces.d.ts

@@ -1,4 +1,4 @@
-import type { AccountKind, AccountCategoryId, UserNameResponse, UserRelationship, ThemePreference } from '@oxy.so/contracts';
+import type { AccountKind, AccountCategoryId, UserNameResponse, UserRelationship, ThemePreference, OxyNotificationEntityType, OxyNotificationType } from '@oxy.so/contracts';
 export interface OxyConfig {
     baseURL: string;
     cloudURL?: string;
@@ -13,6 +13,27 @@ export interface OxyConfig {
      * bounce (which uses the RP origin, not this registered client id).
      */
     clientId?: string;
+    /**
+     * How a BACKEND identifies itself on requests that carry no user session.
+     *
+     * - `'never'` (default): such requests go out anonymous. Right for browsers
+     *   and apps, which have no service identity to offer.
+     * - `'when-anonymous'`: they carry this process's service token instead —
+     *   from `configureServiceAuth()`'s key pair, or, with none, from workload
+     *   attestation (ADR 0026). A user session, when there is one, still wins,
+     *   and a process that can produce no service token (a local checkout) keeps
+     *   sending the request anonymous.
+     *
+     * Why a server wants it: oxy-api charges anonymous traffic to the SOURCE
+     * ADDRESS (`rl:general`, and a +500 ms `slowDown` per request past 100 in 15
+     * minutes), and a fleet leaves through one NAT address, so every anonymous
+     * read a backend makes shares — and past the threshold pays for — one budget.
+     * A first-party service token is exempt from both and charged to its own
+     * application's budget instead. Measured from Mention's task (2026-09-25):
+     * `GET /users/:id` 543–575 ms anonymous past the threshold, `POST
+     * /users/by-ids` 19–24 ms with the service token.
+     */
+    serviceIdentity?: 'never' | 'when-anonymous';
     /**
      * Enable the per-instance GET response cache. Defaults to `true` (5-minute
      * TTL). Set to `false` to disable caching entirely for this instance — GET
@@ -241,25 +262,58 @@ export interface LoginResponse {
     user: User;
     message?: string;
 }
+/**
+ * The actor of a notification as `GET /notifications` populates it — the raw
+ * stored name, not a composed display name.
+ */
+export interface NotificationActor {
+    _id: string;
+    username?: string;
+    name?: {
+        first: string;
+        last: string;
+    };
+    avatar?: string;
+}
+/**
+ * One Oxy notification exactly as the API serializes it
+ * (`packages/api/src/controllers/notification.controller.ts`). `_id` — not
+ * `id` — is the key every notification endpoint addresses it by.
+ */
 export interface Notification {
-    id: string;
-    message: string;
+    _id: string;
+    recipientId: string;
+    /** Populated on a list read; the bare id on a create or a mark-read. */
+    actorId: string | NotificationActor;
     /** One of `OXY_NOTIFICATION_TYPES` (`@oxy.so/contracts`). */
-    type?: string;
+    type: OxyNotificationType;
     /**
-     * `system` notifications only (with `message`): the text an Oxy service sent
-     * about the recipient's own account. Render these two instead of composing a
-     * sentence from actor + entity.
+     * What `entityId` names: `post` | `reply` | `profile`, or `app` — an opaque id
+     * in the notifying application's namespace (`system` notifications only).
+     */
+    entityType: OxyNotificationEntityType;
+    entityId: string;
+    /**
+     * `system` notifications only: the text an Oxy service sent about the
+     * recipient's own account. Render these instead of composing a sentence from
+     * actor + entity.
      */
     title?: string;
+    message?: string;
     /** `system` notifications only: an optional deep link (https or the sending app's scheme). */
     url?: string;
-    /**
-     * What `entityId` names: `post` | `reply` | `profile`, or `app` — an opaque id
-     * in the notifying application's namespace (`system` notifications only).
-     */
-    entityType?: string;
-    entityId?: string;
+    read: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One page of `GET /notifications`, newest first. */
+export interface NotificationPage {
+    notifications: Notification[];
+    /** Unread notifications across ALL pages. */
+    unreadCount: number;
+    hasMore: boolean;
+    page: number;
+    limit: number;
 }
 export interface Wallet {
     id: string;

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

@@ -167,9 +167,9 @@ export interface OxyPagesHeadersOptions {
      * violation for a script we never asked for. The rest of the value is Pages'
      * own default, so caching is unchanged.
      *
-     * And, because this origin is the web identity carrier — where a person's
-     * self-custody root is created, opened, recovered and moved (ADR 0028) — the
-     * rest of the holder policy: no `<base>` and no form posts (`base-uri` /
+     * And, because this origin is where a web account is created, recovered and
+     * deleted and every Oxy passkey is asserted (ADR 0028, ADR 0029) — the rest
+     * of the holder policy: no `<base>` and no form posts (`base-uri` /
      * `form-action 'none'`), no Referer to anyone, passkeys for this origin only
      * with every other powerful feature off (`Permissions-Policy`), and its
      * responses readable by no other origin (`Cross-Origin-Resource-Policy`).

package/dist/types/utils/authWebUrl.d.ts

@@ -15,10 +15,9 @@
  */
 export declare 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 declare const AUTH_WEB_ORIGIN = "https://auth.oxy.so";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.16.0",
+  "version": "1.18.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -118,8 +118,8 @@
     "@oxy.so/telemetry": "^1.1.1",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "^2.0.0",
-    "@oxy.so/protocol": "^1.1.1",
+    "@oxy.so/contracts": "^2.2.0",
+    "@oxy.so/protocol": "^1.1.2",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",
     "express-rate-limit": "^8.6.0",

package/src/HttpService.ts

@@ -38,6 +38,11 @@ interface JwtPayload {
 export type AuthRefreshReason = 'preflight' | 'response-401';
 export type AuthRefreshHandler = (reason: AuthRefreshReason) => Promise<string | null>;
 export type AccessTokenProvider = () => string | null;
+/**
+ * Supplies a bearer for a request made while this client holds NO user session
+ * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
+ */
+export type AnonymousAuthProvider = () => Promise<string | null>;
 
 /**
  * A low-level authenticated request whose response body remains unread.
@@ -378,6 +383,7 @@ export class HttpService {
   private noFresherTokenThan: string | null = null;
   private authRefreshHandler: AuthRefreshHandler | null = null;
   private accessTokenProvider: AccessTokenProvider | null = null;
+  private anonymousAuthProvider: AnonymousAuthProvider | null = null;
   private deviceSecretMintInFlight: Promise<DeviceSecretMintOutcome> | null = null;
   /**
    * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -1191,7 +1197,7 @@ export class HttpService {
   private async getAuthHeader(): Promise<string | null> {
     const accessToken = this.syncAccessTokenFromProvider();
     if (!accessToken) {
-      return null;
+      return this.getAnonymousAuthHeader();
     }
 
     try {
@@ -1222,6 +1228,23 @@ export class HttpService {
     }
   }
 
+  /**
+   * The bearer for a request that has no user session behind it, from the
+   * {@link AnonymousAuthProvider} if one is installed. Never throws: a provider
+   * that fails sends the request anonymous, exactly as it went before any
+   * provider existed.
+   */
+  private async getAnonymousAuthHeader(): Promise<string | null> {
+    if (!this.anonymousAuthProvider) return null;
+    try {
+      const token = await this.anonymousAuthProvider();
+      return token ? `Bearer ${token}` : null;
+    } catch (error) {
+      this.logger.debug('Anonymous auth provider failed; sending the request anonymous:', error);
+      return null;
+    }
+  }
+
   async refreshAccessToken(reason: AuthRefreshReason): Promise<string | null> {
     if (!this.authRefreshHandler) {
       return null;
@@ -1565,6 +1588,17 @@ export class HttpService {
     this.accessTokenProvider = provider;
   }
 
+  /**
+   * Authenticate requests that carry no user session with the bearer this
+   * provider returns — in practice a backend's own service token (see
+   * `OxyConfig.serviceIdentity`). A user session always wins: the provider is
+   * consulted only when there is no access token, and never for `skipAuth`
+   * requests. `null` removes it.
+   */
+  setAnonymousAuthProvider(provider: AnonymousAuthProvider | null): void {
+    this.anonymousAuthProvider = provider;
+  }
+
   clearTokens(): void {
     this.tokenStore.clearTokens();
     // Drop the response cache on logout. The cache is identity-scoped, so a