@oxy.so/core 1.18.1 → 3.0.0

package/dist/types/api/users.d.ts

@@ -0,0 +1,134 @@
+/**
+ * `oxy.users` — people and their profiles.
+ */
+import type { RecommendationItem, RecommendationRequest, UserProfileUpdate } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+import type { SearchProfilesResponse, User } from '../models/interfaces';
+import { type PaginationParams } from '../utils/apiUtils';
+/** A non-local user to find or create (`PUT /users/resolve`). */
+export interface ResolveExternalUserInput {
+    type: 'federated' | 'agent' | 'automated';
+    username: string;
+    actorUri?: string;
+    domain?: string;
+    displayName?: string;
+    avatar?: string;
+    bio?: string;
+    ownerId?: string;
+}
+/**
+ * What proves an account deletion (`DELETE /users/me`):
+ * - `reauth` — an account without a key: a code just sent to its email by
+ *   `oxy.auth.requestReauthCode('delete_account')`, plus its authenticator code
+ *   when it has one;
+ * - `deviceKey` — a Commons account: signed with the identity key held on this
+ *   device (plus `totpCode` when the account has an authenticator).
+ */
+export type DeleteAccountProof = {
+    reauth: {
+        emailCode: {
+            verificationId: string;
+            code: string;
+        };
+        totpCode?: string;
+    };
+} | {
+    deviceKey: true;
+    totpCode?: string;
+};
+export declare class UsersApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * A user by id. Cached 5 minutes; pass `{ cache: false }` for a
+     * registry-fresh read that neither serves nor overwrites a cached entry.
+     */
+    get(userId: string, options?: {
+        cache?: boolean;
+    }): Promise<User>;
+    /**
+     * Many users by id, one round-trip per chunk of 100 — for hydration call
+     * sites that would otherwise issue one `get` per author.
+     *
+     * Ids are deduplicated and blank ids dropped; the result is unordered (map
+     * by `id`). `/users/by-ids` accepts a service token, a user session or an
+     * anonymous caller and returns the same public payload in every case: on a
+     * server that can mint a service token (`OxyServer`) the chunks go over the
+     * service lane — an anonymous call from a backend is charged to its shared
+     * NAT address's per-IP budget — and everywhere else over the user bearer.
+     *
+     * Chunks are independent: a failed chunk is logged and skipped. Not cached.
+     */
+    getMany(ids: string[]): Promise<User[]>;
+    /** The signed-in user. Cached 1 minute. */
+    me(): Promise<User>;
+    /** A profile by username. Cached 5 minutes; `{ cache: false }` as in `get`. */
+    byUsername(username: string, options?: {
+        cache?: boolean;
+    }): Promise<User>;
+    /** The user owning a public key. Public (pre-session): sends no bearer. */
+    byPublicKey(publicKey: string): Promise<User>;
+    /** The user a session belongs to. */
+    bySession(sessionId: string): Promise<User>;
+    /** The users of many sessions in one request; `user` is `null` for a dead session. */
+    bySessions(sessionIds: string[]): Promise<Array<{
+        sessionId: string;
+        user: User | null;
+    }>>;
+    /**
+     * Search profiles. Pass `signal` from a search box: every keystroke would
+     * otherwise run a search to completion while holding a request-queue slot.
+     */
+    search(query: string, pagination?: PaginationParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<SearchProfilesResponse>;
+    /**
+     * Resolve a fediverse handle (`@user@mastodon.social`) to an Oxy profile by
+     * WebFinger. `null` when it cannot be resolved — discovery is best-effort.
+     * Cached 5 minutes: the profile carries the viewer-relative `relationship`.
+     */
+    resolveHandle(handle: string): Promise<User | null>;
+    /**
+     * Find or create a non-local user (federated, agent, automated). All user
+     * creation for external accounts goes through here — services never write
+     * user data directly.
+     */
+    resolveExternal(input: ResolveExternalUserInput): Promise<User>;
+    /** Profiles similar to `userId`, by co-follower overlap. Cached 5 minutes. */
+    similar(userId: string, limitOrPagination?: number | PaginationParams): Promise<User[]>;
+    /**
+     * Profile recommendations. Works signed out (popular public profiles) and
+     * personalises when signed in.
+     *
+     * Only `excludeTypes` / `limit` → the cached `GET /profiles/recommendations`.
+     * Any scored field (`boosts`, `excludeIds`, `signalWeights`, `clientId`,
+     * `offset`) → `POST` with the body validated by `recommendationRequestSchema`
+     * (also cached, keyed on the body).
+     */
+    recommendations(options?: RecommendationRequest): Promise<RecommendationItem[]>;
+    /**
+     * Update the signed-in user's profile and settings (`PUT /users/me`) —
+     * including `notificationPreferences`, `userPreferences` and
+     * `themePreference`.
+     *
+     * Every cached read that can return this user goes, in one pass: the
+     * identity reads (the list `identityCacheSweep` owns) and the account forest
+     * (a personal account IS this user, and `AccountNode.account` embeds it).
+     *
+     * A 401 with no token held rejects with `AUTH_REQUIRED_OFFLINE_SESSION: …` so
+     * the caller knows to sync an offline session before retrying.
+     */
+    updateMe(updates: UserProfileUpdate): Promise<User>;
+    /** Ask for the verified badge. */
+    requestVerification(reason: string, evidence?: string): Promise<{
+        message: string;
+        requestId: string;
+    }>;
+    /**
+     * Delete the signed-in account permanently. `confirmText` must equal the
+     * username. See {@link DeleteAccountProof} for what confirms it.
+     */
+    deleteMe(confirmText: string, proof: DeleteAccountProof): Promise<{
+        message: string;
+    }>;
+}

package/dist/types/boot/sessionColdBoot.d.ts

@@ -14,7 +14,7 @@
  *   2. `device-secret-mint` (web + native) — the zero-cookie transport: when the
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
- *      navigation) and rotate the secret in-use.
+ *      navigation). The secret is stable across mints.
  *   3. `shared-device-adopt` (native, ACCOUNT mode) — this app has no credential
  *      of its own but a sibling official app already put one in the shared native
  *      slot: adopt it and mint. This is how a newly installed official app joins

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

@@ -0,0 +1,10 @@
+/**
+ * `@oxy.so/core/civic` — the Oxy ID QR payloads: parse, build, verify.
+ *
+ * Pure functions over the signed public card and the real-life attestation
+ * QR. Their own entry because verifying a card pulls the protocol's signature
+ * code, which an app that never scans a card should not ship.
+ */
+import '../crypto/polyfill';
+export { parseIdPayload, parseAttestPayload, verifyPublicCardAttestation } from './payloads';
+export type { IdCardRef, AttestQrPayload, ParsedAttestPayload } from './payloads';

package/dist/types/civic/payloads.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Oxy ID / Commons QR payloads — pure, dependency-free helpers (Hermes-safe, no
+ * `URL` global) a scanner can use without an `OxyServices` instance, plus the
+ * client-side check of a public card's Oxy attestation.
+ *
+ * The Oxy ID QR encodes ONLY the DID (`oxycommons://card?did=…&v=1`) — never trust
+ * data — so a card cannot be spoofed by crafting a QR; the scanner resolves the
+ * signed card server-side and re-verifies it. The real-life-attestation QR
+ * (`oxycommons://attest?subject=…&ctx=…&nonce=…&exp=…`) is shown by the person
+ * being attested and parsed by the scanner.
+ */
+import type { ExportAttestation, PublicCard } from '@oxy.so/contracts';
+/** The DID extracted from a scanned `oxycommons://card?did=…` Oxy ID payload. */
+export interface IdCardRef {
+    /** The subject's Oxy DID (`did:web:oxy.so:u:<userId>`). */
+    did: string;
+}
+/**
+ * Parse a scanned / deep-linked Oxy ID payload (`oxycommons://card?did=…`) into
+ * the referenced DID. Pure + dependency-free (Hermes-safe, no `URL` global) so
+ * Commons (and any scanner) can reuse it without an OxyServices instance.
+ *
+ * @param raw - The raw scanned string or deep-link URL.
+ * @returns `{ did }` when a usable DID is present; `null` for anything else (a
+ *   non-card scheme, a missing/empty `did`, or non-string input).
+ */
+export declare function parseIdPayload(raw: string): IdCardRef | null;
+/**
+ * The fields decoded from a scanned real-life-attestation QR
+ * (`oxycommons://attest?subject=…&ctx=…&nonce=…&exp=…`). The SCANNER feeds these
+ * to `oxy.civic.attest`.
+ */
+export interface ParsedAttestPayload {
+    /** The DID of the person being attested (A) — becomes the record's `about`. */
+    subjectDid: string;
+    /** Opaque interaction id (`ctx`); `''` when the QR omitted it. */
+    context: string;
+    /** Single-use replay-guard nonce. */
+    nonce: string;
+    /** Nonce expiry (epoch ms); the server re-checks freshness authoritatively. */
+    exp: number;
+}
+/**
+ * The QR a person shows to be attested in real life, plus the fresh nonce/exp it
+ * embeds so the displaying app can track which scan completed it.
+ */
+export interface AttestQrPayload {
+    /** The `oxycommons://attest?subject=…&ctx=…&nonce=…&exp=…` string to encode as a QR. */
+    payload: string;
+    /** The single-use nonce embedded in the payload. */
+    nonce: string;
+    /** The nonce expiry embedded in the payload (epoch ms). */
+    exp: number;
+}
+/**
+ * Parse a scanned / deep-linked real-life-attestation payload
+ * (`oxycommons://attest?subject=…&ctx=…&nonce=…&exp=…`). Pure + dependency-free
+ * (Hermes-safe, no `URL` global), mirroring {@link parseIdPayload}, so Commons
+ * (and any scanner) can reuse it without an OxyServices instance.
+ *
+ * @param raw - The raw scanned string or deep-link URL.
+ * @returns `{ subjectDid, context, nonce, exp }` when the required fields are
+ *   present and `exp` is a positive finite number; `null` otherwise (a non-attest
+ *   scheme, a missing `subject`/`nonce`/`exp`, an unparseable `exp`, or non-string
+ *   input). `context` defaults to `''` when the QR omits `ctx`.
+ */
+export declare function parseAttestPayload(raw: string): ParsedAttestPayload | null;
+/**
+ * Verify the Oxy custodial attestation on a public card.
+ *
+ * Re-canonicalizes the received `card` (so the order of the JSON keys on the
+ * wire is irrelevant; `canonicalize` also omits any `undefined`-valued optional
+ * key, matching the server which omits absent keys entirely) and checks the
+ * `ES256K-DER-SHA256` signature against `attestation.publicKey`.
+ *
+ * NEVER throws: `verifySignature` already swallows malformed-input
+ * errors and returns `false`, and an absent attestation short-circuits to
+ * `false`. A pure, reusable helper (Commons can call it on a cached card).
+ *
+ * @param card - The card to verify (exactly as received).
+ * @param attestation - The card's attestation, or `null` (unsigned ⇒ `false`).
+ */
+export declare function verifyPublicCardAttestation(card: PublicCard, attestation: ExportAttestation | null): Promise<boolean>;

package/dist/types/client/context.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What every API namespace is built on.
+ *
+ * `OxyServices` creates ONE context and hands it to each namespace it creates
+ * (lazily, on first access). It is the namespaces' only way into the client, so
+ * the plumbing they share — the transport, the service-token lane, cross-cache
+ * invalidation — never becomes public surface on `OxyServices` itself.
+ */
+import type { HttpService, RequestOptions } from '../HttpService';
+import type { OxyServices } from '../OxyServices';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * The service-token lane. Installed only by `OxyServer`
+ * (`@oxy.so/core/server`); `null` on every client. A namespace whose route
+ * accepts a service token as well as a user session (e.g. `users.getMany`)
+ * prefers it when present.
+ */
+export interface ServiceLane {
+    /** Whether a service token can be minted here (a key pair, or workload identity). */
+    readonly available: boolean;
+    request<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions & {
+        actAs?: string;
+    }): Promise<T>;
+}
+export interface OxyContext {
+    /** The client this context belongs to — for calls into other namespaces. */
+    readonly oxy: OxyServices;
+    readonly http: HttpService;
+    /** `oxy.request`: user bearer, rejects with `OxyApiError`. */
+    request<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    /** The service-token lane, or `null` outside a server. */
+    service: ServiceLane | null;
+}

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

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

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

@@ -0,0 +1,24 @@
+/**
+ * `@oxy.so/core/crypto` — the self-custody identity: keys, signatures, the
+ * recovery phrase, and the primitives under them.
+ *
+ * Its own entry so an app that never holds a key never ships secp256k1, bip39
+ * or the AEAD cipher. The `oxy.identity` / `oxy.civic` namespaces load what they
+ * need from here on first use.
+ */
+import './polyfill';
+export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, IdentityUnavailableError, } from './keyManager';
+export type { KeyPair, IdentityStatus, IdentityRecoveryResult } from './keyManager';
+export { readIdentityMarker, updateIdentityMarker } from './identityMarker';
+export type { IdentityMarker } from './identityMarker';
+export type { IdentityDeviceBackupStore } from './deviceBackup';
+export { SignatureService } from './signatureService';
+export type { SignedMessage, AuthChallenge } from './signatureService';
+export { RecoveryPhraseService } from './recoveryPhrase';
+export type { RecoveryPhraseResult, PendingIdentityResult, BackupMaterial } from './recoveryPhrase';
+export { hkdfSha256 } from './kdf';
+export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH } from './aead';
+export type { AeadResult } from './aead';
+export { deriveSharedSecret } from './ecdh';
+export { digestIdentityPayload, signIdentityProof } from './identityProof';
+export { deriveIdentityLinkCode } from './identityLink';

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

@@ -0,0 +1,19 @@
+/**
+ * The one module the API namespaces load crypto through, with `import()`.
+ *
+ * It installs the polyfill FIRST: on Hermes `@noble/hashes` captures
+ * `globalThis.crypto` when it is evaluated, so a namespace that dynamically
+ * imported `./keyManager` directly — before anything installed the shim —
+ * would hand noble `undefined` and every random draw would throw. Loading
+ * through here makes the order a property of the module graph, not of which
+ * entry an app happened to import first.
+ */
+import './polyfill';
+export { KeyManager } from './keyManager';
+export { SignatureService } from './signatureService';
+export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase';
+export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH } from './aead';
+export { digestIdentityPayload, signIdentityProof } from './identityProof';
+export { deriveIdentityLinkCode } from './identityLink';
+export { solveRegistrationPow } from './registrationPow';
+export { canonicalize, signMessage, verifySignature } from '@oxy.so/protocol';

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

@@ -7,15 +7,16 @@
  * Guard order when installing a `getRandomValues` shim (see bottom of file and
  * {@link cryptoPolyfill}):
  *
- *   1. A REAL `globalThis.crypto.getRandomValues` — used as-is (browser, Node
+ *   1. A REAL `globalThis.crypto.getRandomValues` — used as-is (browsers, Node
  *      >= 20, modern Hermes). The shim below is only installed when the host is
  *      missing it, so this branch is the install-time gate.
- *   2. Node — backed by the built-in `node:crypto` module (`webcrypto`, else
- *      `randomFillSync`). This is what a Node runtime WITHOUT a global WebCrypto
- *      (Node 18 script entrypoints, some embedded hosts) falls back to.
- *   3. React Native — `expo-crypto.getRandomBytes`, through the dependency-free
+ *   2. React Native — `expo-crypto.getRandomBytes`, through the dependency-free
  *      `@oxy.so/protocol/random` entry.
  *
+ * There is deliberately no `node:crypto` branch: every supported Node has a
+ * global WebCrypto, and a `require('node:crypto')` here made web bundlers ship
+ * Node's crypto, stream and buffer polyfills (~600 KB) to every browser.
+ *
  * # Evaluation order — this module must import NOTHING that can capture the global
  *
  * `@noble/hashes` 1.x reads `globalThis.crypto` exactly once, when its
@@ -31,10 +32,6 @@
  * and `index.ts` imports this file first. `__tests__/polyfillOrder.test.ts`
  * guards both halves.
  *
- * Historically step (2) delegated to `@oxy.so/protocol`'s RN-only
- * `getRandomBytesRN`, which THROWS on Node — so any Node host lacking a global
- * WebCrypto crashed here instead of getting randomness. It is now a proper
- * Node-backed implementation.
  */
 import { Buffer } from 'buffer';
 export { Buffer };

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

@@ -1,6 +1,6 @@
 /**
  * Registration proof-of-work — the CLIENT half of the anti-automation nonce
- * `register()` (`mixins/OxyServices.auth.ts`) submits alongside the
+ * `auth.registerKey()` (`api/auth.ts`) submits alongside the
  * registration signature. The message format, difficulty and the full design
  * rationale (why 16 bits, why sequential nonces are fine, what this is and
  * isn't a defense against) live in `@oxy.so/protocol`'s

package/dist/types/i18n/accountCategoryLabels.d.ts

@@ -3,7 +3,7 @@ import type { AccountCategoryId } from '@oxy.so/contracts';
  * Every account category's English name, keyed by its stable id.
  *
  * **The annotation is the point.** The vocabulary lives in `@oxy.so/contracts`
- * and the names live in `locales/en-US.json`, so they are two lists that must
+ * and the names live in `locales/en-US.ts`, so they are two lists that must
  * agree and nothing but a type can make them. Declaring the JSON node as a
  * TOTAL `Record<AccountCategoryId, string>` turns "somebody added a category at
  * Oxy and nobody wrote its English" into a `TS2741` naming the missing id, at

package/dist/types/i18n/accountRoleLabels.d.ts

@@ -1,4 +1,4 @@
-import type { AccountRole } from '../mixins/OxyServices.accounts';
+import type { AccountRole } from '../api/accounts';
 /**
  * Every account member role's English name, keyed by its stable id.
  *

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

@@ -1,3 +1,22 @@
-export type LocaleDict = Record<string, any>;
+/** A nested dictionary of strings. */
+export interface LocaleDict {
+    [key: string]: string | LocaleDict | LocaleDict[] | string[];
+}
+/**
+ * Load the dictionary serving `locale`. Resolves `true` once it is available
+ * (immediately for English or one already loaded), `false` if it failed to load
+ * — `translate` then keeps serving English.
+ */
+export declare function loadLocale(locale: string | undefined): Promise<boolean>;
+/** Whether the dictionary serving `locale` is loaded (English always is). */
+export declare function isLocaleLoaded(locale: string | undefined): boolean;
+/**
+ * Subscribe to dictionaries finishing loading (for re-rendering once a
+ * language arrives). Returns the unsubscribe. Pair with {@link getLocalesVersion}
+ * in `useSyncExternalStore`.
+ */
+export declare function subscribeLocales(listener: () => void): () => void;
+/** Bumps each time a dictionary loads. */
+export declare function getLocalesVersion(): number;
 export declare function translate(locale: string | undefined, key: string, vars?: Record<string, string | number>): string;
 export declare function hasKey(locale: string | undefined, key: string): boolean;