@oxy.so/core 1.0.0

package/dist/esm/boot/sessionColdBoot.js

@@ -0,0 +1,392 @@
+/**
+ * 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 { runColdBoot } from '../utils/coldBoot.js';
+import { isNative as detectNative } from '../utils/platform.js';
+import { logger } from '../logger/index.js';
+import { computeIdentityTag } from '../utils/cacheKey.js';
+import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh.js';
+import { establishIdentitySession, resolveIdentityPin, } from '../session/identitySession.js';
+import { decideSharedDeviceJoin, } from '../session/sharedDeviceCredential.js';
+/**
+ * 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 async function runSessionColdBoot(opts) {
+    const { oxy, store } = opts;
+    const isNative = opts.platform?.isNative ?? detectNative();
+    // Non-null ONLY in identity mode; every `!== null` test below therefore reads
+    // as "is this boot identity-bound?" while also narrowing the binding.
+    const identityBinding = opts.sessionMode === 'identity' ? opts.identity ?? null : null;
+    if (opts.sessionMode === 'identity' && identityBinding === null) {
+        logger.error('runSessionColdBoot: sessionMode "identity" requires an `identity` binding — refusing to run any lane (an identity-bound client must never adopt the device active account)', undefined, { component: 'sessionColdBoot', method: 'runSessionColdBoot' });
+        await opts.onSignedOut?.('error');
+        return { kind: 'unauthenticated' };
+    }
+    // Best-effort connectivity gate for the NETWORK steps only. A missing hint or
+    // any non-`true` verdict means "assume online" — never falsely skip a real
+    // sign-in on an ambiguous probe.
+    const isOffline = () => opts.isOffline?.() ?? false;
+    // Boot-local (not module-level) so it cannot leak across boots or break under
+    // bundler re-evaluation.
+    let signedOutReason = 'no_session';
+    // Boot-local memo for the identity pin. Resolved lazily INSIDE a step so the
+    // (local, but storage-backed) read is covered by `overallDeadlineMs`, and
+    // resolved at most once per boot so two steps cannot disagree. Always `null`
+    // in account mode.
+    let pinResolved = false;
+    let cachedPin = null;
+    const getIdentityPin = async () => {
+        if (identityBinding === null) {
+            return null;
+        }
+        if (!pinResolved) {
+            cachedPin = await resolveIdentityPin(identityBinding);
+            pinResolved = true;
+        }
+        return cachedPin;
+    };
+    const steps = [];
+    // 1. warm-token-plant (web + native) — the fastest path. When the persisted
+    //    store already holds a still-valid warm access token (its expiry more than
+    //    the refresh lead window away) plus its owning session identity, plant it
+    //    and yield the session IMMEDIATELY, skipping the blocking mint round-trip on
+    //    first paint. The token is used AS-IS: this step NEVER mints, rotates, or
+    //    persists anything. The proactive `startTokenRefreshScheduler` + the
+    //    request-time preflight (both wired in the services provider) rotate it in
+    //    the background; a revoked token self-heals via the 401 -> re-mint -> clear
+    //    path. This exposure is sanctioned by `authStateStore.ts` (~L30-36): the
+    //    warm token is short-lived and adds nothing over the already-persisted
+    //    `deviceSecret`.
+    steps.push({
+        id: 'warm-token-plant',
+        run: async () => {
+            const persisted = await store.load();
+            if (!persisted?.accessToken || !persisted.sessionId || !persisted.userId || !persisted.expiresAt) {
+                return { kind: 'skip' };
+            }
+            // Guard a malformed `expiresAt` (Date.parse -> NaN): treat as not-valid and
+            // fall through to the mint lane. A token still inside the refresh lead
+            // window (or already expired) is likewise skipped — let the mint lane get a
+            // fresh one rather than plant a token about to expire.
+            const expiresAtMs = new Date(persisted.expiresAt).getTime();
+            if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now() + TOKEN_REFRESH_LEAD_MS) {
+                return { kind: 'skip' };
+            }
+            if (identityBinding !== null) {
+                // Identity-bound: a persisted token is only acceptable when it belongs to
+                // the PINNED account. Both the token's own claim (`computeIdentityTag`,
+                // the same derivation `SessionClient.applyState` uses) and the owning
+                // session identity must match — a token planted for another account by an
+                // earlier account-mode write is exactly the durable drift this gate stops.
+                const pin = await getIdentityPin();
+                if (pin === null ||
+                    persisted.userId !== pin.accountId ||
+                    computeIdentityTag(persisted.accessToken) !== pin.accountId) {
+                    return { kind: 'skip' };
+                }
+            }
+            oxy.setTokens(persisted.accessToken);
+            return {
+                kind: 'session',
+                session: {
+                    sessionId: persisted.sessionId,
+                    userId: persisted.userId,
+                    accessToken: persisted.accessToken,
+                },
+            };
+        },
+    });
+    // 2. device-secret-mint (web + native) — the zero-cookie fast path. When the
+    //    origin persisted a deviceId + deviceSecret, mint a short access token with
+    //    a single bearer-less POST (no cookie, no navigation). The mint itself runs
+    //    through `refreshDeviceSecretArm`, which acquires the client's PROCESS-WIDE
+    //    single-flight, persists `nextDeviceSecret` BEFORE planting the token, and
+    //    returns a classified outcome — so concurrent mint lanes share one in-flight
+    //    request and the durable store always converges on the server's credential.
+    steps.push({
+        id: 'device-secret-mint',
+        // Network step — skip entirely when the caller reports the device offline so
+        // a doomed mint cannot burn the overall deadline before routing settles.
+        enabled: () => !isOffline(),
+        run: async () => {
+            const pin = await getIdentityPin();
+            if (identityBinding !== null && pin === null) {
+                // Identity-bound with no verified pin (never written, or cleared because
+                // the local key changed/vanished). An UNPINNED mint would adopt whichever
+                // account the device is currently switched to — the exact drift this mode
+                // exists to prevent. Fall through to `identity-key-signin`, which
+                // re-derives the account from the local key and rewrites the pin.
+                return { kind: 'skip' };
+            }
+            const result = await refreshDeviceSecretArm({ oxy, store, pin });
+            switch (result.status) {
+                case 'ok':
+                    // The arm persisted nextDeviceSecret and planted the token.
+                    return {
+                        kind: 'session',
+                        session: {
+                            sessionId: result.sessionId,
+                            userId: result.userId,
+                            accessToken: result.token,
+                            state: result.state,
+                        },
+                    };
+                case 'invalid-secret': {
+                    // Stale/diverged secret — drop it so the mint lane stops firing. On
+                    // native the shared-key step below can still recover; on web this ends
+                    // signed out. Setting it undefined drops the key on the store's JSON
+                    // serialization, and the mint guard treats undefined as absent.
+                    const persisted = await store.load();
+                    if (persisted) {
+                        await store.save({ ...persisted, deviceSecret: undefined });
+                    }
+                    return { kind: 'skip' };
+                }
+                case 'no-session':
+                    // Device known, no live session — authoritative signed-out. Keep the
+                    // secret (the device may sign in again).
+                    signedOutReason = 'no_session';
+                    return { kind: 'skip' };
+                case 'persist-failed':
+                    // The mint rotated the secret but it could not be durably persisted —
+                    // refuse to advertise a session that will not survive a reload. Keep
+                    // the secret; a later boot/attempt re-mints once storage recovers.
+                    logger.error('device-secret mint rotated the secret but it could not be durably persisted — not planting', undefined, { component: 'sessionColdBoot', method: 'device-secret-mint' });
+                    return { kind: 'skip' };
+                case 'account-not-on-device':
+                    // Pinned mint rejected: the pinned account is no longer a live account
+                    // of this device session. The secret is healthy — keep it untouched and
+                    // let `identity-key-signin` re-establish from the local key.
+                    logger.debug('pinned device-secret mint rejected (account_not_on_device) — keeping secret, re-establishing from the identity key', { component: 'sessionColdBoot', method: 'device-secret-mint' });
+                    return { kind: 'skip' };
+                case 'transient':
+                    // Network / 5xx: keep the secret; a later attempt can succeed.
+                    logger.debug('device-secret mint failed (transient) — keeping secret', { component: 'sessionColdBoot', method: 'device-secret-mint' });
+                    return { kind: 'skip' };
+                case 'no-secret':
+                    return { kind: 'skip' };
+            }
+        },
+    });
+    if (identityBinding !== null) {
+        // 3-identity. identity-key-signin — re-mint from THIS device's PRIMARY
+        //    identity key (`getPublicKey` → challenge → sign → verify). It REPLACES
+        //    `shared-key-signin`, which reads the CROSS-APP shared keychain slot and
+        //    may therefore hold a different identity than the device's primary — the
+        //    one thing an identity-bound client must never adopt. The server resolves
+        //    the account from the verified signer, so the winning session is
+        //    identity-authoritative and the pin is (re)written from it.
+        //
+        //    Online-gated like every network step; `{ retry: false }` keeps the two
+        //    round-trips single attempts (the refresh scheduler / 401 lane own later
+        //    retries) so this step cannot multiply boot latency. On web
+        //    `KeyManager.getPublicKey()` resolves to `null`, so it skips.
+        steps.push({
+            id: 'identity-key-signin',
+            enabled: () => !isOffline(),
+            run: async () => {
+                const established = await establishIdentitySession({
+                    oxy,
+                    store,
+                    binding: identityBinding,
+                    requestOptions: { retry: false },
+                });
+                const accessToken = established?.session.accessToken;
+                if (!established || !accessToken) {
+                    return { kind: 'skip' };
+                }
+                return {
+                    kind: 'session',
+                    session: {
+                        sessionId: established.session.sessionId,
+                        userId: established.session.user.id,
+                        accessToken,
+                    },
+                };
+            },
+        });
+    }
+    else if (opts.sharedDeviceCredential) {
+        // 3. shared-device-adopt (native, ACCOUNT mode) — join the device's existing
+        //    session through the shared native credential slot.
+        //
+        //    This is the lane that separates identity from session transport. What it
+        //    reads is an ordinary, individually revocable `deviceId` + `deviceSecret`
+        //    put there by a sibling official app — never the Commons private key. It
+        //    is what lets a freshly installed official app land signed in with no QR,
+        //    and it is why an ordinary app never needs identity-key access at all.
+        //
+        //    `decideSharedDeviceJoin` gates it: an app that already holds its own
+        //    credential is never moved, and an UNREADABLE slot is never mistaken for
+        //    an empty one. The lane therefore cannot sign anyone out, in either
+        //    upgrade order.
+        const sharedSlot = opts.sharedDeviceCredential;
+        steps.push({
+            id: 'shared-device-adopt',
+            // The adoption itself is local, but it is only worth committing alongside
+            // a mint that proves the credential — so the whole lane is online-gated
+            // like every other network step.
+            enabled: () => isNative && !isOffline(),
+            run: async () => {
+                const before = await store.load();
+                const decision = decideSharedDeviceJoin(before, await sharedSlot.read());
+                if (decision.action === 'skip') {
+                    logger.debug(`shared device credential not adopted (${decision.reason})`, { component: 'sessionColdBoot', method: 'shared-device-adopt' });
+                    return { kind: 'skip' };
+                }
+                // Restore the store to exactly what it held before this lane touched it.
+                // A credential we adopted and could not prove must not be left behind for
+                // the next boot's mint lane to keep retrying.
+                const revert = async () => {
+                    if (before) {
+                        await store.save(before);
+                    }
+                    else {
+                        await store.clear();
+                    }
+                };
+                const adopted = {
+                    // The mint fills both in from the device's live state; carrying the
+                    // previous session's ids into a different device session would be a
+                    // lie for however long the mint takes.
+                    sessionId: '',
+                    userId: '',
+                    deviceId: decision.credential.deviceId,
+                    deviceSecret: decision.credential.deviceSecret,
+                };
+                if (!(await store.save(adopted))) {
+                    logger.error('adopted the shared device credential but it could not be durably persisted — reverting', undefined, { component: 'sessionColdBoot', method: 'shared-device-adopt' });
+                    await revert();
+                    return { kind: 'skip' };
+                }
+                const result = await refreshDeviceSecretArm({ oxy, store, pin: null });
+                if (result.status === 'ok') {
+                    return {
+                        kind: 'session',
+                        session: {
+                            sessionId: result.sessionId,
+                            userId: result.userId,
+                            accessToken: result.token,
+                        },
+                    };
+                }
+                if (result.status === 'invalid-secret') {
+                    // The one place we hold POSITIVE proof that the exact bytes in the
+                    // shared slot are dead — the server rejected them by name. Clearing it
+                    // signs nobody out (a credential the server does not recognise cannot
+                    // be minting for anyone) and it is what stops a dead credential from
+                    // blocking every future install: a stale slot owned by a different
+                    // `deviceId` is otherwise never overwritten, by design.
+                    await sharedSlot.clear();
+                }
+                else if (result.status === 'no-session') {
+                    signedOutReason = 'no_session';
+                }
+                await revert();
+                return { kind: 'skip' };
+            },
+        });
+    }
+    if (identityBinding === null) {
+        // 4. shared-key-signin (native) — the RECOVERY / COMPATIBILITY lane: sign a
+        //    challenge with the shared-keychain IDENTITY key to re-mint a session.
+        //
+        //    It runs LAST on purpose. Using the self-custody key to obtain an ordinary
+        //    session is the over-sharing #937 sets out to end, so it is now reachable
+        //    only on a device where no sibling app has published a shared device
+        //    credential yet — an install that predates this lane, or one where the
+        //    shared slot is unreadable. Its own `store.save` below feeds the shared
+        //    slot through the mirroring store, so the FIRST boot that takes this lane
+        //    is also the last one that needs to: every later app joins by credential.
+        //
+        //    Native AND online: it is a network step (challenge + verify round-trips),
+        //    so it is gated by the same offline hint as the mint lane. `{ retry: false }`
+        //    keeps the two round-trips as single attempts — the refresh scheduler /
+        //    401 lane own later retries — so this step cannot multiply boot latency.
+        steps.push({
+            id: 'shared-key-signin',
+            enabled: () => isNative && !isOffline(),
+            run: async () => {
+                const session = await oxy.signInWithSharedIdentity({ requestOptions: { retry: false } });
+                if (!session?.accessToken) {
+                    return { kind: 'skip' };
+                }
+                // `verifyChallenge` mints a rotating deviceSecret; persist it so the next
+                // boot can use the faster device-secret-mint lane (sockets + tab-focus
+                // re-mint depend on the credential being in the store).
+                if (session.deviceId && session.deviceSecret) {
+                    await store.save({
+                        sessionId: session.sessionId,
+                        userId: session.user.id,
+                        deviceId: session.deviceId,
+                        deviceSecret: session.deviceSecret,
+                        accessToken: session.accessToken,
+                        expiresAt: session.expiresAt,
+                    });
+                }
+                return {
+                    kind: 'session',
+                    session: {
+                        sessionId: session.sessionId,
+                        userId: session.user.id,
+                        accessToken: session.accessToken,
+                    },
+                };
+            },
+        });
+    }
+    const outcome = await runColdBoot({
+        steps,
+        overallDeadlineMs: opts.overallDeadlineMs,
+        onStepDeadline: opts.onStepDeadline,
+        onStepError: (id, error) => {
+            signedOutReason = 'error';
+            opts.onStepError?.(id, error);
+        },
+    });
+    if (outcome.kind === 'session') {
+        await opts.onSession?.({ ...outcome.session, via: outcome.via });
+        return outcome;
+    }
+    await opts.onSignedOut?.(signedOutReason);
+    return outcome;
+}

package/dist/esm/constants/version.js

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

package/dist/esm/crypto/aead.js

@@ -0,0 +1,74 @@
+/**
+ * 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()`.
+ */
+// Loading the polyfill guarantees `globalThis.crypto.getRandomValues` exists on
+// every platform (native crypto on web/Node; expo-crypto-backed shim on RN).
+import './polyfill.js';
+import { xchacha20poly1305 } from '@noble/ciphers/chacha';
+/** Key length for XChaCha20-Poly1305, in bytes (256-bit). */
+export const AEAD_KEY_LENGTH = 32;
+/** Nonce length for XChaCha20-Poly1305, in bytes (192-bit). */
+export const AEAD_NONCE_LENGTH = 24;
+function assertKey(key) {
+    if (key.length !== AEAD_KEY_LENGTH) {
+        throw new Error(`AEAD key must be ${AEAD_KEY_LENGTH} bytes, got ${key.length}`);
+    }
+}
+/** Generate a fresh 24-byte random nonce via the platform CSPRNG. */
+function randomNonce() {
+    const nonce = new Uint8Array(AEAD_NONCE_LENGTH);
+    globalThis.crypto.getRandomValues(nonce);
+    return nonce;
+}
+/**
+ * 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 function encryptAead(key, plaintext, aad) {
+    assertKey(key);
+    const nonce = randomNonce();
+    const ciphertext = xchacha20poly1305(key, nonce, aad).encrypt(plaintext);
+    return { nonce, ciphertext };
+}
+/**
+ * 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 function decryptAead(key, nonce, ciphertext, aad) {
+    assertKey(key);
+    if (nonce.length !== AEAD_NONCE_LENGTH) {
+        throw new Error(`AEAD nonce must be ${AEAD_NONCE_LENGTH} bytes, got ${nonce.length}`);
+    }
+    return xchacha20poly1305(key, nonce, aad).decrypt(ciphertext);
+}

package/dist/esm/crypto/ecdh.js

@@ -0,0 +1,32 @@
+/**
+ * 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()`.
+ */
+import { deriveSecp256k1SharedSecret } from '@oxy.so/protocol/secp256k1';
+/**
+ * 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 function deriveSharedSecret(privateKeyHex, otherPublicKeyHex) {
+    return deriveSecp256k1SharedSecret(privateKeyHex, otherPublicKeyHex);
+}