@oxy.so/core 1.0.0

package/dist/types/OxyServices.d.ts

@@ -0,0 +1,139 @@
+/**
+ * OxyServices - Unified client for Oxy API and Oxy Cloud
+ *
+ * # Usage Examples
+ *
+ * ## Browser (ESM/TypeScript)
+ *
+ * ```typescript
+ * import { OxyServices } from './core/OxyServices';
+ *
+ * const oxy = new OxyServices({
+ *   baseURL: 'https://api.oxy.so',
+ *   cloudURL: 'https://cloud.oxy.so',
+ * });
+ *
+ * // Authenticate and fetch user
+ * await oxy.setTokens('ACCESS_TOKEN');
+ * const user = await oxy.getCurrentUser();
+ *
+ * // Upload a file (browser File API)
+ * const fileInput = document.querySelector('input[type=file]');
+ * const file = fileInput.files[0];
+ * await oxy.uploadRawFile(file);
+ *
+ * // Get a file download URL for <img src>
+ * const url = oxy.getFileDownloadUrl('fileId', 'thumb');
+ * ```
+ *
+ * ## Node.js (CommonJS/TypeScript)
+ *
+ * ```typescript
+ * import { OxyServices } from './core/OxyServices';
+ * import fs from 'fs';
+ *
+ * const oxy = new OxyServices({
+ *   baseURL: 'https://api.oxy.so',
+ *   cloudURL: 'https://cloud.oxy.so',
+ * });
+ *
+ * // Authenticate and fetch user
+ * await oxy.setTokens('ACCESS_TOKEN');
+ * const user = await oxy.getCurrentUser();
+ *
+ * // Upload a file (Node.js Buffer)
+ * const buffer = fs.readFileSync('myfile.png');
+ * const blob = new Blob([buffer]);
+ * await oxy.uploadRawFile(blob, { filename: 'myfile.png' });
+ *
+ * // Get a file download URL
+ * const url = oxy.getFileDownloadUrl('fileId');
+ * ```
+ *
+ * ## Configuration
+ * - `baseURL`: Oxy API endpoint (e.g., https://api.oxy.so)
+ * - `cloudURL`: Oxy Cloud/CDN endpoint (e.g., https://cloud.oxy.so)
+ *
+ * See method JSDoc for more details and options.
+ */
+import { type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
+import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices.errors';
+import { composeOxyServices } from './mixins';
+/**
+ * OxyServices - Unified client library for interacting with the Oxy API
+ *
+ * This class provides all API functionality in one simple, easy-to-use interface.
+ *
+ * ## Architecture
+ * - **HttpService**: Unified HTTP service handling authentication, caching, deduplication, queuing, and retry
+ * - **OxyServices**: Provides high-level API methods
+ *
+ * ## Mixin Composition
+ * The class is composed using TypeScript mixins for better code organization:
+ * - **Base**: Core infrastructure (HTTP client, request management, error handling)
+ * - **Auth**: Authentication and session management
+ * - **User**: User profiles, follow, notifications
+ * - **Privacy**: Blocked and restricted users
+ * - **Language**: Language detection and metadata
+ * - **Payment**: Payment processing
+ * - **Reputation**: Reputation system (Oxy Trust)
+ * - **Assets**: File upload and asset management
+ * - **Accounts**: Unified account graph (tree, members, roles, bot credentials)
+ *   and the applications owned within it (Application = OAuth client)
+ * - **Connected apps**: OAuth-consent surface (public app identity, grants)
+ * - **Location**: Location-based features
+ * - **Analytics**: Analytics tracking
+ * - **Devices**: Device management
+ * - **Utility**: Utility methods and Express middleware
+ *
+ * @example
+ * ```typescript
+ * const oxy = new OxyServices({
+ *   baseURL: 'https://api.oxy.so',
+ *   cloudURL: 'https://cloud.oxy.so'
+ * });
+ * ```
+ */
+declare const OxyServicesComposed: import("./mixins").ComposedOxyServicesConstructor;
+export declare class OxyServices extends OxyServicesComposed {
+    constructor(config: OxyConfig);
+}
+export interface OxyServices extends InstanceType<ReturnType<typeof composeOxyServices>> {
+    createLinkedClient(config: OxyConfig): LinkedHttpClient;
+    auth(options?: {
+        debug?: boolean;
+        onError?: (error: unknown) => unknown;
+        loadUser?: boolean;
+        optional?: boolean;
+        serviceTokenJwksUrl?: string;
+        jwtSecret?: string;
+        expectedIssuer?: string;
+        expectedAudience?: string;
+    }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
+    authSocket(options?: {
+        debug?: boolean;
+    }): (socket: unknown, next: (err?: Error) => void) => Promise<void>;
+    serviceAuth(options?: {
+        debug?: boolean;
+        serviceTokenJwksUrl?: string;
+        jwtSecret?: string;
+        expectedIssuer?: string;
+        expectedAudience?: string;
+    }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
+    requireScope(scope: string): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+    assetUpdateVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown>;
+}
+export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError };
+/**
+ * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.
+ */
+export declare const OXY_CLOUD_URL = "https://cloud.oxy.so";
+/**
+ * Export the default Oxy API URL (for documentation)
+ */
+export declare const OXY_API_URL: string;
+/**
+ * Pre-configured client instance for easy import
+ * Uses OXY_API_URL as baseURL and OXY_CLOUD_URL as cloudURL
+ */
+export declare const oxyClient: OxyServices;

package/dist/types/OxyServices.errors.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Custom error types for better error handling
+ */
+export declare class OxyAuthenticationError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code?: string, status?: number);
+}
+/**
+ * Thrown when an asset's authorized download URL cannot be resolved.
+ *
+ * `getFileDownloadUrlAsync` asks the API for a URL that is valid for the
+ * CALLER and the asset's actual visibility. When that resolution fails there is
+ * no honest fallback: the public CDN origin only serves `public` assets, so
+ * handing back `https://cloud.oxy.so/<id>` for an unresolved asset produces a
+ * hard 404 at render time and hides the real failure from the caller. This
+ * error surfaces the failure instead.
+ *
+ * The message and fields deliberately carry only the asset id, the requested
+ * variant and the HTTP status — never the resolved URL, which embeds a scoped
+ * media token.
+ *
+ * ## `status` lets a caller decide whether a CDN fallback is safe
+ *
+ * Core itself never falls back to the public CDN builder, because it has no
+ * knowledge of the asset's visibility and that URL is a guaranteed 404 for a
+ * private asset. A CALLER that knows an asset is public MAY choose to fall back
+ * to `getFileDownloadUrl(id, variant)` — but only for a TRANSIENT failure, not
+ * a definitive denial:
+ *   - `status` 401/403/404 → definitive: the asset is private/denied/missing.
+ *     Never CDN-fall-back — it will 404.
+ *   - `status` undefined (network error) or 5xx → transient: resolution itself
+ *     failed. If the caller independently knows the asset is public, a CDN
+ *     fallback is defensible best-effort.
+ */
+export declare class AssetUrlResolutionError extends Error {
+    readonly code = "ASSET_URL_UNRESOLVED";
+    readonly fileId: string;
+    readonly variant?: string;
+    readonly status?: number;
+    /**
+     * The underlying transport/API failure, when there was one. Declared on the
+     * class rather than relying on `Error.cause` because this package targets
+     * ES2020, where `cause` is not part of the `Error` type.
+     */
+    readonly cause?: unknown;
+    constructor(fileId: string, variant: string | undefined, status: number | undefined, cause?: unknown);
+}
+/**
+ * Thrown when one or more chunks of `getServiceAssetMetadataByIds` could not be
+ * resolved.
+ *
+ * Exists because for this endpoint a FAILED request and an ABSENT asset produce
+ * the same observable result. The server legitimately omits unknown/deleted ids,
+ * so callers are documented to map the response by `id` and treat a missing
+ * entry as "no such asset" — which means a chunk that 429s, times out or 5xxs
+ * reads as authoritative absence unless it is raised.
+ *
+ * That was not hypothetical: a metadata backfill counted every throttled asset
+ * as needing no update and exited 0, and the MTN signed-record builder embedded
+ * media with no content hash into records that are immutable once signed. Both
+ * paths reported success and wrote nothing.
+ *
+ * `unresolvedIds` carries every id in a failed chunk — not the subset the server
+ * would have omitted anyway, which is unknowable when the request never landed.
+ * A caller that wants best-effort passes `{ partial: true }` and never sees this.
+ */
+export declare class ServiceAssetMetadataError extends Error {
+    readonly code = "SERVICE_ASSET_METADATA_UNRESOLVED";
+    /** Every id belonging to a chunk whose request failed. */
+    readonly unresolvedIds: string[];
+    /** HTTP statuses observed across the failed chunks (deduped, ascending). */
+    readonly statuses: number[];
+    /**
+     * The first underlying transport/API failure. Declared on the class rather
+     * than relying on `Error.cause` because this package targets ES2020, where
+     * `cause` is not part of the `Error` type.
+     */
+    readonly cause?: unknown;
+    constructor(unresolvedIds: string[], statuses: number[], cause?: unknown);
+}
+export declare class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
+    constructor(operationName: string, timeoutMs: number);
+}

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

@@ -0,0 +1,140 @@
+/**
+ * Device-first session cold boot for every consumer.
+ *
+ * On a fresh page load / app launch this resolves the device's session in a
+ * deterministic order, built on the pure `runColdBoot` primitive. It NEVER
+ * redirects to a login page: an unresolved boot ends in a signed-out state that
+ * the app renders with a "Sign in with Oxy" button.
+ *
+ * Ordered steps (first to yield a session wins):
+ *   1. `warm-token-plant` (web + native) — the fastest path: when the persisted
+ *      store still holds a warm access token that is valid for more than the
+ *      refresh lead window, plant it and yield the session with NO network
+ *      round-trip. The background scheduler rotates it shortly after.
+ *   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.
+ *   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
+ *      the device's existing session WITHOUT another QR and without ever touching
+ *      the Commons private key.
+ *   4. `shared-key-signin` (native, ACCOUNT mode) — the legacy lane: re-mint by
+ *      signing with the shared-keychain IDENTITY key. Retained as a recovery /
+ *      compatibility path for devices whose apps have not yet published a shared
+ *      device credential — OR `identity-key-signin` (IDENTITY mode) — re-mint
+ *      from THIS device's primary identity key.
+ *   5. Signed out.
+ *
+ * Two session modes (see {@link RunSessionColdBootOptions.sessionMode}):
+ *   - `account` (default) — the device's ACTIVE account owns the session. Every
+ *     Oxy app but the identity vault boots this way; behaviour is unchanged.
+ *   - `identity` — the owner of the local PRIMARY identity key owns the session,
+ *     permanently, regardless of which account the device is switched to. Each
+ *     step above is bound to the persisted identity pin, and the shared-keychain
+ *     lane is replaced by the primary-key one (the shared slot is a CROSS-APP
+ *     slot that may hold a different identity).
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import { type ColdBootOutcome } from '../utils/coldBoot';
+import { type IdentityBinding } from '../session/identitySession';
+import { type SharedDeviceCredentialStore } from '../session/sharedDeviceCredential';
+import type { OxyServices } from '../OxyServices';
+import type { AuthStateStore } from '../session/authStateStore';
+import type { DeviceSessionState } from '@oxy.so/contracts';
+/**
+ * Who owns the session this boot resolves.
+ *
+ * - `account` — the device's active account (every ordinary Oxy app).
+ * - `identity` — the owner of the device's primary identity key (the identity
+ *   vault). Requires {@link RunSessionColdBootOptions.identity}.
+ */
+export type SessionMode = 'account' | 'identity';
+/** The winning session shape a cold-boot step reports. */
+export interface DeviceBootSession {
+    sessionId: string;
+    userId: string;
+    accessToken: string;
+    /** Server state already returned by the mint; absent on warm-token restore. */
+    state?: DeviceSessionState;
+}
+/** Why a cold boot ended without a session. */
+export type SignedOutReason = 'no_session' | 'error';
+export interface RunSessionColdBootOptions {
+    oxy: OxyServices;
+    store: AuthStateStore;
+    /** Platform hints; default derived from `@oxy.so/core`'s platform detection. */
+    platform?: {
+        isWeb?: boolean;
+        isNative?: boolean;
+    };
+    /** Invoked with the winning session (token already planted). */
+    onSession?: (session: DeviceBootSession & {
+        via: string;
+    }) => void | Promise<void>;
+    /** Invoked when the boot ended signed out. */
+    onSignedOut?: (reason: SignedOutReason) => void | Promise<void>;
+    onStepError?: (id: string, error: unknown) => void;
+    /**
+     * HARD overall deadline (ms) for the whole ordered step chain, forwarded to
+     * {@link runColdBoot}. Defense-in-depth so a single non-settling network step
+     * (a black-hole network that neither connects nor rejects) can NEVER hang the
+     * boot — and therefore app routing — indefinitely. Inert on healthy loads
+     * (every step settles well under it); only trips on pathological networks.
+     * When omitted there is no overall deadline (unchanged behavior).
+     */
+    overallDeadlineMs?: number;
+    /**
+     * Invoked once per step abandoned because {@link overallDeadlineMs} expired
+     * before it settled. Forwarded to {@link runColdBoot}. Must not throw.
+     */
+    onStepDeadline?: (stepId: string) => void;
+    /**
+     * Best-effort connectivity hint. When it returns `true` the two NETWORK steps
+     * (`device-secret-mint`, `shared-key-signin`) are skipped — an offline device
+     * cannot mint, and attempting to would burn the whole deadline on a doomed
+     * request before routing settles. The pure-local `warm-token-plant` step is
+     * NEVER gated by this: an offline returning user with an unexpired persisted
+     * token must still boot authenticated. Only an EXPLICIT offline verdict should
+     * be returned; the caller resolves unknown/timeout to `false` (assume online)
+     * so a flaky probe can never falsely skip a real sign-in.
+     */
+    isOffline?: () => boolean;
+    /**
+     * Who owns the resolved session. Defaults to `'account'` — the device's active
+     * account — which is the behaviour every ordinary Oxy app has today and which
+     * this option leaves byte-for-byte unchanged.
+     *
+     * `'identity'` binds the boot to the owner of this device's PRIMARY identity
+     * key and REQUIRES {@link identity}. When it is missing the boot refuses to
+     * run any lane (an identity-bound client silently falling back to the device's
+     * active account is precisely the bug this mode exists to prevent) and
+     * resolves signed out.
+     */
+    sessionMode?: SessionMode;
+    /**
+     * The identity binding (pin store + key/signature access) used by
+     * `sessionMode: 'identity'`. Ignored in `'account'` mode.
+     */
+    identity?: IdentityBinding;
+    /**
+     * The cross-app native slot holding this device's shared DeviceSession
+     * credential, enabling the `shared-device-adopt` lane. Supplied by
+     * `@oxy.so/services` on native; absent on web, where each origin is its own
+     * device by design.
+     *
+     * IGNORED in `sessionMode: 'identity'`. The shared slot belongs to whichever
+     * principal signed in on this device; an identity-bound client must resolve
+     * its session from the local key alone, and adopting a device credential is
+     * exactly the drift that mode exists to prevent.
+     */
+    sharedDeviceCredential?: SharedDeviceCredentialStore;
+}
+/**
+ * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
+ * a side effect, invokes `onSession` (winning session, token already planted) or
+ * `onSignedOut` (no session).
+ */
+export declare function runSessionColdBoot(opts: RunSessionColdBootOptions): Promise<ColdBootOutcome<DeviceBootSession>>;

package/dist/types/constants/version.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Package version and metadata constants
+ * This file is auto-generated to avoid runtime dependency on package.json
+ */
+export declare const packageInfo: {
+    readonly name: "@oxy.so/services";
+    readonly version: "5.2.1";
+    readonly description: "Reusable OxyHQ module to handle authentication, user management, reputation system (Oxy Trust) and more 🚀";
+    readonly main: "lib/commonjs/node/index.js";
+    readonly module: "lib/module/node/index.js";
+    readonly types: "lib/typescript/node/index.d.ts";
+};
+export declare const name: "@oxy.so/services", version: "5.2.1", description: "Reusable OxyHQ module to handle authentication, user management, reputation system (Oxy Trust) and more 🚀";

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

@@ -0,0 +1,56 @@
+/**
+ * Authenticated Encryption with Associated Data (XChaCha20-Poly1305)
+ *
+ * Pure-JS/TS AEAD via `@noble/ciphers` — identical behaviour on web, Node, and
+ * React Native with zero WebCrypto / native-module dependency. This replaces
+ * the `crypto.subtle`-based path (unreliable on React Native) for the Commons
+ * encrypted backup and device-to-device transfer flows.
+ *
+ * XChaCha20-Poly1305 is chosen over AES-GCM specifically for its 24-byte
+ * (192-bit) random nonce: the nonce space is large enough that random nonces
+ * never collide in practice, so callers do not need to maintain a per-key
+ * counter. The 16-byte Poly1305 tag is appended to the ciphertext by the
+ * underlying library and validated on decrypt.
+ *
+ * The optional Associated Data (AAD) is authenticated but NOT encrypted: it
+ * binds the ciphertext to its context (e.g. a backup version, a device id, a
+ * DID). Decryption fails if the key, nonce, ciphertext, OR aad differ from
+ * those used at encryption time.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+import './polyfill';
+/** Key length for XChaCha20-Poly1305, in bytes (256-bit). */
+export declare const AEAD_KEY_LENGTH = 32;
+/** Nonce length for XChaCha20-Poly1305, in bytes (192-bit). */
+export declare const AEAD_NONCE_LENGTH = 24;
+/** Ciphertext (Poly1305 tag appended) plus the random nonce used to produce it. */
+export interface AeadResult {
+    /** The 24-byte random nonce. Store/transmit alongside the ciphertext. */
+    nonce: Uint8Array;
+    /** Ciphertext with the 16-byte Poly1305 authentication tag appended. */
+    ciphertext: Uint8Array;
+}
+/**
+ * Encrypt `plaintext` under `key` with a fresh random nonce, authenticating the
+ * optional `aad`.
+ *
+ * @param key       32-byte symmetric key (e.g. from `hkdfSha256`).
+ * @param plaintext Bytes to encrypt.
+ * @param aad       Optional associated data authenticated but not encrypted.
+ * @returns         `{ nonce, ciphertext }` — both are required to decrypt.
+ */
+export declare function encryptAead(key: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): AeadResult;
+/**
+ * Decrypt and authenticate `ciphertext` produced by {@link encryptAead}.
+ *
+ * Throws if the key, nonce, ciphertext, or aad differ from those used at
+ * encryption time (tamper detection), or if the tag is invalid.
+ *
+ * @param key        32-byte symmetric key.
+ * @param nonce      The 24-byte nonce returned by `encryptAead`.
+ * @param ciphertext Ciphertext with the appended Poly1305 tag.
+ * @param aad        The same associated data supplied at encryption time.
+ * @returns          The recovered plaintext bytes.
+ */
+export declare function decryptAead(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;

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

@@ -0,0 +1,29 @@
+/**
+ * ECDH shared-secret derivation (secp256k1)
+ *
+ * Derives a raw 32-byte ECDH shared secret from a local private key and a
+ * remote public key, using the shared `@oxy.so/protocol` secp256k1 primitive.
+ * This is the key-exchange
+ * step for the Commons device-to-device transfer flow: each side computes the
+ * same shared secret, which is then run through `hkdfSha256` to derive the
+ * symmetric key handed to `encryptAead` / `decryptAead`.
+ *
+ * The returned value is the raw x-coordinate of the ECDH point, big-endian,
+ * zero-padded to 32 bytes. It is NOT itself a symmetric key — always pass it
+ * through a KDF (HKDF) with a context-binding `info` before use.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+/**
+ * Compute the ECDH shared secret between a local private key and a remote
+ * public key on secp256k1.
+ *
+ * Symmetric by construction:
+ * `deriveSharedSecret(privA, pubB) === deriveSharedSecret(privB, pubA)`.
+ *
+ * @param privateKeyHex     Local private key, hex (up to 64 chars; canonicalized).
+ * @param otherPublicKeyHex Remote public key, hex — compressed (`02`/`03` + 32
+ *                          bytes) or uncompressed (`04` + 64 bytes).
+ * @returns                 The 32-byte big-endian shared secret.
+ */
+export declare function deriveSharedSecret(privateKeyHex: string, otherPublicKeyHex: string): Uint8Array;

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

@@ -0,0 +1,94 @@
+/**
+ * Identity marker — a NON-secret, AndroidKeyStore-independent record that an
+ * identity exists (or existed) on this device.
+ *
+ * WHY THIS EXISTS: the identity private/public keys live in expo-secure-store,
+ * whose Android backing (a single `key_v1` AndroidKeyStore key by default) can be
+ * invalidated by an OS/vendor keystore event. When that happens SDK 57's
+ * expo-secure-store DELETES the undecryptable ciphertext on the read path and
+ * returns `null` — indistinguishable, from the keys alone, from a genuinely
+ * fresh install. That ambiguity is what lets a real identity get silently
+ * replaced by the onboarding "create" flow.
+ *
+ * The marker breaks the tie. It is written to AsyncStorage (RN) / localStorage
+ * (web) — storage that is NOT protected by the identity's AndroidKeyStore key —
+ * so it SURVIVES a keystore death. `getIdentityStatus()` reads it: keys empty +
+ * marker present ⇒ `lost` (route to recovery, NEVER welcome/create); keys empty
+ * + no marker ⇒ `absent` (the only path to fresh onboarding).
+ *
+ * It holds only the PUBLIC key plus provenance metadata — never any secret — so
+ * persisting it in plain KV storage adds no exposure.
+ *
+ * Every operation fails OPEN (returns null / false / resolves): the marker is a
+ * best-effort disambiguation signal layered on top of the authoritative
+ * secure-store reads, never a gate that can itself lock the user out.
+ *
+ * ESM-safe (no `require()`); zero React/RN static imports — the RN AsyncStorage
+ * module is reached only through `@oxy.so/protocol`'s per-platform dynamic loader.
+ */
+/**
+ * AsyncStorage / localStorage key holding the serialized {@link IdentityMarker}.
+ * `.v1` lets a future shape change ship a `.v2` key without misreading a stale
+ * blob. Distinct from every `oxy_identity_*` secure-store key so it never
+ * collides with the keychain material it disambiguates.
+ */
+export declare const IDENTITY_MARKER_STORAGE_KEY = "oxy_identity_marker_v1";
+/**
+ * A durable, non-secret record that an identity was provisioned on this device.
+ *
+ * `publicKey` is the identity's public key (NOT secret) — it lets recovery
+ * validate that whatever it restores is the SAME account this marker records,
+ * never a silent account switch. `origin` records how the identity came to be.
+ * `onboardingComplete` mirrors the onboarding milestone (Workstream 3.4) so a
+ * lost SecureStore milestone flag cannot re-route a real identity into the
+ * onboarding wizard.
+ */
+export interface IdentityMarker {
+    v: 1;
+    /** The identity's PUBLIC key — never secret. */
+    publicKey: string;
+    createdAt: number;
+    origin: 'create' | 'import' | 'restore' | 'backfill';
+    /** Milestone mirror: `true` once onboarding has completed for this identity. */
+    onboardingComplete?: boolean;
+}
+/** Fields accepted when creating a marker; `createdAt` defaults to now. */
+export interface WriteIdentityMarkerInput {
+    publicKey: string;
+    origin: IdentityMarker['origin'];
+    createdAt?: number;
+    onboardingComplete?: boolean;
+}
+/**
+ * Read the identity marker. Fails OPEN: returns `null` on any storage error,
+ * missing entry, or malformed blob — the caller treats "no marker" as the safe
+ * default (fresh install), and the authoritative secure-store read decides the
+ * rest.
+ */
+export declare function readIdentityMarker(): Promise<IdentityMarker | null>;
+/**
+ * Write (create/replace) the marker. Returns `true` when it durably landed,
+ * `false` when storage was unavailable or the write threw. Callers treat a
+ * `false` as non-fatal — the marker is best-effort and a subsequent read
+ * re-backfills it from the healthy key pair.
+ */
+export declare function writeIdentityMarker(input: WriteIdentityMarkerInput): Promise<boolean>;
+/**
+ * Merge a partial update into the existing marker, preserving every field the
+ * caller does not override (notably `createdAt` and `onboardingComplete`). When
+ * no marker exists yet, a partial carrying at least `publicKey` + `origin`
+ * creates one; otherwise the update is a no-op returning `false`.
+ *
+ * Used to (a) mirror the onboarding milestone (`{ onboardingComplete: true }`)
+ * without disturbing provenance, and (b) refresh `origin` on a same-identity
+ * re-persist without resetting `createdAt`.
+ */
+export declare function updateIdentityMarker(partial: Partial<Omit<IdentityMarker, 'v'>>): Promise<boolean>;
+/**
+ * Remove the marker. Called ONLY after the identity's keys have been
+ * successfully deleted (`KeyManager.deleteIdentity`), so a marker never outlives
+ * the identity it records. Fails open (swallows errors) — a leftover marker
+ * simply routes a truly-absent identity to `recovery` instead of `welcome`,
+ * which is the safe direction.
+ */
+export declare function clearIdentityMarker(): Promise<void>;

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

@@ -0,0 +1,25 @@
+/**
+ * Key Derivation Function (HKDF-SHA256)
+ *
+ * Pure-JS/TS HKDF via `@noble/hashes` — identical behaviour on web, Node, and
+ * React Native with zero WebCrypto / native-module dependency. Used to derive
+ * fixed-length symmetric keys from higher-entropy input keying material (an
+ * ECDH shared secret, a recovery-phrase seed, etc.) for the Commons encrypted
+ * backup and device-to-device transfer flows.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+/**
+ * Derive `length` bytes of keying material from `ikm` using HKDF-SHA256
+ * (RFC 5869 — extract-then-expand).
+ *
+ * @param ikm    Input keying material (the raw secret; NOT necessarily uniform).
+ * @param salt   Non-secret random salt. An empty array is treated by HKDF as a
+ *               zero-filled salt of the hash length — pass a real salt whenever
+ *               one is available so derivations for different contexts diverge.
+ * @param info   Context/application-binding string ("what is this key for").
+ *               Distinct `info` values yield independent keys from the same ikm.
+ * @param length Number of output bytes. Must be in (0, 255 * 32].
+ * @returns      Exactly `length` bytes of derived keying material.
+ */
+export declare function hkdfSha256(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array, length: number): Uint8Array;