@oxy.so/core 1.0.0

package/dist/esm/crypto/polyfill.js

@@ -0,0 +1,129 @@
+/**
+ * Crypto Polyfills
+ *
+ * Ensures Buffer and crypto.getRandomValues are available
+ * across all platforms (Node.js, Browser, React Native).
+ *
+ * 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
+ *      >= 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` (statically imported via the
+ *      per-platform `platform/crypto` module in `@oxy.so/protocol`).
+ *
+ * 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 _cjs_buffer from 'buffer';
+const { Buffer } = _cjs_buffer;
+import { getRandomBytesRN, isNodeJS } from '@oxy.so/protocol';
+const getGlobalObject = () => {
+    if (typeof globalThis !== 'undefined')
+        return globalThis;
+    if (typeof global !== 'undefined')
+        return global;
+    if (typeof window !== 'undefined')
+        return window;
+    if (typeof self !== 'undefined')
+        return self;
+    return {};
+};
+const globalObject = getGlobalObject();
+// Make Buffer available globally for libraries that depend on it
+if (!globalObject.Buffer) {
+    globalObject.Buffer = Buffer;
+}
+/**
+ * Lazily-resolved `node:crypto` module, cached after the first attempt.
+ * `undefined` = not tried yet; `null` = tried and unavailable (non-Node host).
+ */
+let cachedNodeCrypto;
+/**
+ * Synchronously load `node:crypto` on a Node runtime, or `null` elsewhere.
+ *
+ * Uses a guarded, Node-only `require`. Every runtime that actually reaches this
+ * branch has a working CommonJS `require`: `@oxy.so/core` publishes no
+ * `"type": "module"`, so Node loads it as CommonJS and the `require` free
+ * variable is present. Browsers never reach here (they own `globalThis.crypto`,
+ * so this polyfill is never installed) and React Native takes the
+ * `getRandomBytesRN` branch — so the `node:crypto` reference is dead code in
+ * those bundles, and Expo's Metro resolver shims `node:*` builtins, keeping
+ * web/native bundles green.
+ */
+function loadNodeCryptoSync() {
+    if (cachedNodeCrypto !== undefined) {
+        return cachedNodeCrypto;
+    }
+    if (typeof require !== 'function') {
+        cachedNodeCrypto = null;
+        return cachedNodeCrypto;
+    }
+    try {
+        cachedNodeCrypto = require('node:crypto');
+    }
+    catch {
+        // No Node crypto (unexpected on a real Node host) — degrade to the next
+        // mechanism rather than crash.
+        cachedNodeCrypto = null;
+    }
+    return cachedNodeCrypto;
+}
+/**
+ * Fill `array` with cryptographically-secure random bytes from `node:crypto`.
+ * Prefers `webcrypto.getRandomValues`; falls back to `randomFillSync`. Returns
+ * `false` when Node crypto is unavailable so the caller can try the next
+ * mechanism.
+ */
+function fillFromNodeCrypto(array) {
+    const nodeCrypto = loadNodeCryptoSync();
+    if (!nodeCrypto) {
+        return false;
+    }
+    const webcrypto = nodeCrypto.webcrypto;
+    if (webcrypto && typeof webcrypto.getRandomValues === 'function') {
+        try {
+            webcrypto.getRandomValues(array);
+            return true;
+        }
+        catch {
+            // `webcrypto.getRandomValues` rejects non-integer views (Float*Array,
+            // DataView); fall through to `randomFillSync`, which accepts any view.
+        }
+    }
+    if (typeof nodeCrypto.randomFillSync === 'function') {
+        nodeCrypto.randomFillSync(array);
+        return true;
+    }
+    return false;
+}
+const cryptoPolyfill = {
+    getRandomValues(array) {
+        // Node: back the CSPRNG with `node:crypto`. This is the path that matters on
+        // Node runtimes shipping WITHOUT a global WebCrypto — where delegating to
+        // the RN-only expo-crypto stub would throw.
+        if (isNodeJS() && fillFromNodeCrypto(array)) {
+            return array;
+        }
+        // React Native (and any non-Node host without WebCrypto): synchronous
+        // expo-crypto via @oxy.so/protocol's RN `platform/crypto` variant.
+        const bytes = getRandomBytesRN(array.byteLength);
+        const uint8View = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
+        uint8View.set(bytes);
+        return array;
+    },
+};
+// Only polyfill if crypto or crypto.getRandomValues is not available
+if (typeof globalObject.crypto === 'undefined') {
+    globalObject.crypto = cryptoPolyfill;
+}
+else if (typeof globalObject.crypto.getRandomValues !== 'function') {
+    globalObject.crypto.getRandomValues = cryptoPolyfill.getRandomValues;
+}
+export { Buffer };

package/dist/esm/crypto/recoveryPhrase.js

@@ -0,0 +1,238 @@
+/**
+ * Recovery Phrase Service - BIP39 Mnemonic Generation
+ *
+ * Handles generation and restoration of recovery phrases (mnemonic seeds)
+ * for backing up and restoring user identities.
+ *
+ * Note: This module requires the polyfill to be loaded first (done via crypto/index.ts)
+ *
+ * Oxy recovery phrases are English-only, so the English wordlist is imported by
+ * its own subpath. Never reach for a package that exposes its wordlists through
+ * a barrel: `bip39`'s `_wordlists` hard-requires all ten languages, which put
+ * ~265 KB of unreachable wordlists into the initial chunk of every consuming
+ * app. Adding another language means one more subpath import, ideally lazy.
+ */
+import { generateMnemonic, mnemonicToSeed, validateMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english';
+import { KeyManager } from './keyManager.js';
+import { hkdfSha256 } from './kdf.js';
+/**
+ * Convert Uint8Array or array-like to hexadecimal string
+ * Works in both Node.js and React Native without depending on Buffer
+ */
+function toHex(data) {
+    // Convert to array of numbers if needed
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    return Array.from(bytes)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/** UTF-8 encode an ASCII label to bytes (for HKDF salt/info). */
+function utf8(label) {
+    return new TextEncoder().encode(label);
+}
+/**
+ * HKDF context tag for the encrypted-backup key schedule (b3 Feature 1). Used as
+ * the HKDF `salt`; distinct from any other Oxy key-derivation salt so the backup
+ * key schedule is independent. Versioned so a future scheme change is a new tag.
+ */
+export const BACKUP_KDF_SALT = 'oxy-identity-backup-v1';
+/** HKDF `info` label that derives the symmetric AEAD key from the seed. */
+export const BACKUP_KDF_ENCRYPTION_INFO = 'oxy-backup-encryption-key';
+/** HKDF `info` label that derives the (server-hashed) backup locator from the seed. */
+export const BACKUP_KDF_LOOKUP_INFO = 'oxy-backup-lookup-id';
+/** Byte length of both the derived backup key and the derived lookup id (256-bit). */
+export const BACKUP_MATERIAL_LENGTH = 32;
+export class RecoveryPhraseService {
+    /**
+     * Generate a new identity with a recovery phrase.
+     * The mnemonic phrase MUST be shown to the user exactly once after this
+     * call resolves — if it is lost, the account becomes unrecoverable.
+     *
+     * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+     *
+     * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
+     */
+    static async generateIdentityWithRecovery(options) {
+        // Generate 128-bit entropy for 12-word mnemonic
+        const mnemonic = generateMnemonic(wordlist, 128);
+        // Derive private key from mnemonic
+        // Using the seed directly as the private key (simplified approach)
+        const seed = await mnemonicToSeed(mnemonic);
+        // Use first 32 bytes of seed as private key
+        const privateKeyHex = toHex(seed.subarray(0, 32));
+        // Import the derived key pair. KeyManager.importKeyPair will refuse to
+        // clobber an existing identity unless overwrite is explicitly requested.
+        const publicKey = await KeyManager.importKeyPair(privateKeyHex, {
+            overwrite: options?.overwrite === true,
+        });
+        return {
+            phrase: mnemonic,
+            words: mnemonic.split(' '),
+            publicKey,
+        };
+    }
+    /**
+     * Generate a 24-word recovery phrase for higher security.
+     *
+     * Same overwrite-protection semantics as `generateIdentityWithRecovery`.
+     */
+    static async generateIdentityWithRecovery24(options) {
+        // Generate 256-bit entropy for 24-word mnemonic
+        const mnemonic = generateMnemonic(wordlist, 256);
+        const seed = await mnemonicToSeed(mnemonic);
+        const privateKeyHex = toHex(seed.subarray(0, 32));
+        const publicKey = await KeyManager.importKeyPair(privateKeyHex, {
+            overwrite: options?.overwrite === true,
+        });
+        return {
+            phrase: mnemonic,
+            words: mnemonic.split(' '),
+            publicKey,
+        };
+    }
+    /**
+     * Derive a brand-new identity + recovery phrase WITHOUT persisting anything.
+     *
+     * Pure: same derivation as {@link generateIdentityWithRecovery} (128-bit
+     * mnemonic → seed → first 32 bytes as the secp256k1 private key) but it stops
+     * BEFORE `KeyManager.importKeyPair`, so no on-device identity is touched. The
+     * caller decides if/when to commit the material (e.g. only after a server
+     * confirms a key rotation). Works on web too — it never reads or writes secure
+     * storage.
+     *
+     * The 12-word `phrase` MUST be shown to the user before the identity is
+     * committed anywhere — if it is lost the account becomes unrecoverable.
+     */
+    static async derivePendingIdentity() {
+        const mnemonic = generateMnemonic(wordlist, 128);
+        const seed = await mnemonicToSeed(mnemonic);
+        const privateKey = toHex(seed.subarray(0, 32));
+        const publicKey = KeyManager.derivePublicKey(privateKey);
+        return {
+            phrase: mnemonic,
+            words: mnemonic.split(' '),
+            privateKey,
+            publicKey,
+        };
+    }
+    /**
+     * Derive the private key from a recovery phrase WITHOUT storing it.
+     *
+     * The private-key counterpart of {@link derivePublicKeyFromPhrase}. Used to
+     * re-derive a key in memory (e.g. to sign a rotation proof with the current
+     * key when the device has no SecureStore copy). Never persists — the returned
+     * material lives only in the caller's memory.
+     */
+    static async derivePrivateKeyFromPhrase(phrase) {
+        const normalizedPhrase = phrase.trim().toLowerCase();
+        if (!validateMnemonic(normalizedPhrase, wordlist)) {
+            throw new Error('Invalid recovery phrase');
+        }
+        const seed = await mnemonicToSeed(normalizedPhrase);
+        return toHex(seed.subarray(0, 32));
+    }
+    /**
+     * Derive the encrypted-backup key material from a recovery phrase (b3 Feature
+     * 1). PURE and additive — it does NOT touch the frozen phrase→privateKey
+     * derivation ({@link derivePrivateKeyFromPhrase} slices the first 32 seed
+     * bytes) and never reads or writes secure storage.
+     *
+     * Both outputs are derived from the FULL 64-byte BIP-39 seed via HKDF-SHA256
+     * with domain-separated `info` labels, so the domain separation is real: a
+     * device compromise that leaks only the raw 32-byte private key can compute
+     * NEITHER the backup key nor the lookup id (both need the whole seed). Locating
+     * AND decrypting a backup therefore requires the recovery phrase.
+     *
+     * @param phrase - The BIP-39 recovery phrase (validated + normalized here).
+     * @returns `{ backupKey, lookupId }` — the AEAD key (kept local) and the hex
+     *   locator (uploaded; server stores only its hash).
+     * @throws if the phrase is not a valid BIP-39 mnemonic.
+     */
+    static async deriveBackupMaterial(phrase) {
+        const normalizedPhrase = phrase.trim().toLowerCase();
+        if (!validateMnemonic(normalizedPhrase, wordlist)) {
+            throw new Error('Invalid recovery phrase. Please check the words and try again.');
+        }
+        const seed = await mnemonicToSeed(normalizedPhrase);
+        const salt = utf8(BACKUP_KDF_SALT);
+        const backupKey = hkdfSha256(seed, salt, utf8(BACKUP_KDF_ENCRYPTION_INFO), BACKUP_MATERIAL_LENGTH);
+        const lookupId = toHex(hkdfSha256(seed, salt, utf8(BACKUP_KDF_LOOKUP_INFO), BACKUP_MATERIAL_LENGTH));
+        return { backupKey, lookupId };
+    }
+    /**
+     * Restore an identity from a recovery phrase.
+     *
+     * Refuses to overwrite a DIFFERENT existing identity unless
+     * `options.overwrite === true`. Re-importing the same phrase that
+     * matches the current identity is always allowed (it's a no-op refresh
+     * of the backup record).
+     */
+    static async restoreFromPhrase(phrase, options) {
+        // Normalize and validate the phrase
+        const normalizedPhrase = phrase.trim().toLowerCase();
+        if (!validateMnemonic(normalizedPhrase, wordlist)) {
+            throw new Error('Invalid recovery phrase. Please check the words and try again.');
+        }
+        // Derive the same private key from the mnemonic
+        const seed = await mnemonicToSeed(normalizedPhrase);
+        const privateKeyHex = toHex(seed.subarray(0, 32));
+        // Import and store the key pair
+        const publicKey = await KeyManager.importKeyPair(privateKeyHex, {
+            overwrite: options?.overwrite === true,
+        });
+        return publicKey;
+    }
+    /**
+     * Validate a recovery phrase without importing it
+     */
+    static validatePhrase(phrase) {
+        const normalizedPhrase = phrase.trim().toLowerCase();
+        return validateMnemonic(normalizedPhrase, wordlist);
+    }
+    /**
+     * Get the word list for autocomplete/validation
+     */
+    static getWordList() {
+        return wordlist;
+    }
+    /**
+     * Check if a word is valid in the BIP39 word list
+     */
+    static isValidWord(word) {
+        return wordlist.includes(word.toLowerCase());
+    }
+    /**
+     * Get suggestions for a partial word
+     */
+    static getSuggestions(partial, limit = 5) {
+        const lowerPartial = partial.toLowerCase();
+        return wordlist.filter((word) => word.startsWith(lowerPartial)).slice(0, limit);
+    }
+    /**
+     * Derive the public key from a phrase without storing
+     * Useful for verification before importing
+     */
+    static async derivePublicKeyFromPhrase(phrase) {
+        const normalizedPhrase = phrase.trim().toLowerCase();
+        if (!validateMnemonic(normalizedPhrase, wordlist)) {
+            throw new Error('Invalid recovery phrase');
+        }
+        const seed = await mnemonicToSeed(normalizedPhrase);
+        const privateKeyHex = toHex(seed.subarray(0, 32));
+        return KeyManager.derivePublicKey(privateKeyHex);
+    }
+    /**
+     * Convert a phrase to its word array
+     */
+    static phraseToWords(phrase) {
+        return phrase.trim().toLowerCase().split(/\s+/);
+    }
+    /**
+     * Convert a word array to a phrase string
+     */
+    static wordsToPhrase(words) {
+        return words.map(w => w.toLowerCase().trim()).join(' ');
+    }
+}
+export default RecoveryPhraseService;

package/dist/esm/crypto/signatureService.js

@@ -0,0 +1,269 @@
+/**
+ * Signature Service - ECDSA Digital Signatures (device-key bound)
+ *
+ * Handles signing and verification of messages with the user's DEVICE identity
+ * key (read from {@link KeyManager} / secure storage). All cryptography itself —
+ * canonical signing input, SHA-256, secp256k1 sign/verify, envelope assembly —
+ * is delegated to `@oxy.so/protocol`; this service only resolves the key from
+ * storage and orchestrates the protocol primitives.
+ */
+import { signEnvelope, signMessage, verifySignature, sha256, loadExpoCrypto, loadNodeCrypto, isReactNative, isNodeJS, } from '@oxy.so/protocol';
+import { KeyManager } from './keyManager.js';
+import { logger } from '../logger/index.js';
+export class SignatureService {
+    /**
+     * Generate a random challenge string (for offline use)
+     * Uses expo-crypto in React Native, crypto.randomBytes in Node.js
+     */
+    static async generateChallenge() {
+        // In React Native, use expo-crypto
+        if (isReactNative()) {
+            const Crypto = await loadExpoCrypto();
+            const randomBytes = await Crypto.getRandomBytesAsync(32);
+            return Array.from(new Uint8Array(randomBytes))
+                .map((b) => b.toString(16).padStart(2, '0'))
+                .join('');
+        }
+        if (isNodeJS()) {
+            try {
+                const nodeCrypto = await loadNodeCrypto();
+                return nodeCrypto.randomBytes(32).toString('hex');
+            }
+            catch (error) {
+                // Node crypto failed to load — log and fall through to Web Crypto API
+                logger.warn('[oxy.crypto] Node crypto unavailable, falling back to Web Crypto', { component: 'SignatureService' }, error);
+            }
+        }
+        // Browser: use Web Crypto API
+        const bytes = new Uint8Array(32);
+        globalThis.crypto.getRandomValues(bytes);
+        return Array.from(bytes)
+            .map(b => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+    /**
+     * Hash a message using SHA-256
+     */
+    static async hashMessage(message) {
+        return sha256(message);
+    }
+    /**
+     * Sign a message using the stored device private key
+     * Returns the signature in DER format (hex encoded)
+     */
+    static async sign(message) {
+        const privateKey = await KeyManager.getPrivateKey();
+        if (!privateKey) {
+            throw new Error('No identity found. Please create or import an identity first.');
+        }
+        return signMessage(message, privateKey);
+    }
+    /**
+     * Create a signed message object with metadata
+     */
+    static async createSignedMessage(message) {
+        const publicKey = await KeyManager.getPublicKey();
+        if (!publicKey) {
+            throw new Error('No identity found. Please create or import an identity first.');
+        }
+        const timestamp = Date.now();
+        const messageWithTimestamp = `${message}:${timestamp}`;
+        const signature = await SignatureService.sign(messageWithTimestamp);
+        return {
+            message,
+            signature,
+            publicKey,
+            timestamp,
+        };
+    }
+    /**
+     * Verify a signed message object
+     * Checks both signature validity and timestamp freshness
+     */
+    static async verifySignedMessage(signedMessage, maxAgeMs = 5 * 60 * 1000 // 5 minutes default
+    ) {
+        const { message, signature, publicKey, timestamp } = signedMessage;
+        // Check timestamp freshness
+        const now = Date.now();
+        if (now - timestamp > maxAgeMs) {
+            return false;
+        }
+        // Verify signature
+        const messageWithTimestamp = `${message}:${timestamp}`;
+        return verifySignature(messageWithTimestamp, signature, publicKey);
+    }
+    /**
+     * Create a signed authentication challenge response
+     * Used for challenge-response authentication
+     */
+    static async signChallenge(challenge) {
+        const publicKey = await KeyManager.getPublicKey();
+        if (!publicKey) {
+            throw new Error('No identity found. Please create or import an identity first.');
+        }
+        const timestamp = Date.now();
+        const message = `auth:${publicKey}:${challenge}:${timestamp}`;
+        const signature = await SignatureService.sign(message);
+        return {
+            challenge: signature,
+            publicKey,
+            timestamp,
+        };
+    }
+    /**
+     * Create a signed authentication challenge response using the SHARED identity
+     * key (the cross-app `group.so.oxy.shared` keychain key), not the primary
+     * device key.
+     *
+     * Mirrors {@link signChallenge} exactly — same message format
+     * (`auth:${publicKey}:${challenge}:${timestamp}`) so the server verification
+     * path is unchanged — but sources the shared public/private key from
+     * `KeyManager` and signs with the protocol's explicit-key {@link signMessage}.
+     * Used by "Sign in with Oxy" same-device shared-keychain SSO (Mechanism A): a
+     * sibling native app proves control of the shared identity to mint its own
+     * session.
+     *
+     * Throws if no shared identity exists (native-only; the shared keychain is
+     * unavailable on web).
+     */
+    static async signChallengeWithSharedKey(challenge) {
+        const publicKey = await KeyManager.getSharedPublicKey();
+        const privateKey = await KeyManager.getSharedPrivateKey();
+        if (!publicKey || !privateKey) {
+            throw new Error('No shared identity found. Cannot sign with the shared key.');
+        }
+        const timestamp = Date.now();
+        const message = `auth:${publicKey}:${challenge}:${timestamp}`;
+        const signature = await signMessage(message, privateKey);
+        return {
+            challenge: signature,
+            publicKey,
+            timestamp,
+        };
+    }
+    /**
+     * Verify a challenge response
+     */
+    static async verifyChallengeResponse(originalChallenge, response, maxAgeMs = 5 * 60 * 1000) {
+        const { challenge: signature, publicKey, timestamp } = response;
+        // Check timestamp freshness
+        const now = Date.now();
+        if (now - timestamp > maxAgeMs) {
+            return false;
+        }
+        const message = `auth:${publicKey}:${originalChallenge}:${timestamp}`;
+        return verifySignature(message, signature, publicKey);
+    }
+    /**
+     * Create a registration signature
+     * Used when registering a new identity with the server
+     * Format matches server expectation: oxy:register:{publicKey}:{timestamp}
+     */
+    static async createRegistrationSignature() {
+        const publicKey = await KeyManager.getPublicKey();
+        if (!publicKey) {
+            throw new Error('No identity found. Please create or import an identity first.');
+        }
+        const timestamp = Date.now();
+        const message = `oxy:register:${publicKey}:${timestamp}`;
+        const signature = await SignatureService.sign(message);
+        return {
+            signature,
+            publicKey,
+            timestamp,
+        };
+    }
+    /**
+     * Sign arbitrary data for API requests
+     * Creates a canonical string representation and signs it
+     */
+    static async signRequestData(data) {
+        const publicKey = await KeyManager.getPublicKey();
+        if (!publicKey) {
+            throw new Error('No identity found. Please create or import an identity first.');
+        }
+        const timestamp = Date.now();
+        // Create canonical string representation
+        const sortedKeys = Object.keys(data).sort();
+        const canonicalParts = sortedKeys.map(key => `${key}:${JSON.stringify(data[key])}`);
+        const canonicalString = canonicalParts.join('|');
+        const message = `request:${publicKey}:${timestamp}:${canonicalString}`;
+        const signature = await SignatureService.sign(message);
+        return {
+            signature,
+            publicKey,
+            timestamp,
+        };
+    }
+    /**
+     * Build a signed-record envelope for a self-issued identity/profile record.
+     *
+     * The envelope is self-issued: `issuer` equals `subject` (the signer's DID).
+     * The signature covers the canonical JSON of every field EXCEPT `publicKey`
+     * and `signature`; `alg` is `ES256K-DER-SHA256` (secp256k1 over the SHA-256 of
+     * the canonical bytes, DER-encoded). The cryptography is delegated to the
+     * protocol's {@link signEnvelope}, which derives the (uncompressed-hex)
+     * `publicKey` from the stored device key — identical to the registered
+     * verification method.
+     *
+     * Requires a stored identity (native secure storage); throws if none exists.
+     *
+     * @param type - The record category (`'identity'` or `'profile'`).
+     * @param subject - The subject DID the record is about (also the issuer).
+     * @param record - The arbitrary record payload to attest to.
+     */
+    static async signRecord(type, subject, record) {
+        const privateKey = await KeyManager.getPrivateKey();
+        if (!privateKey) {
+            throw new Error('No identity found. Please create or import an identity first.');
+        }
+        return signEnvelope({
+            version: 1,
+            type,
+            subject,
+            issuer: subject,
+            record,
+            issuedAt: Date.now(),
+        }, privateKey);
+    }
+    /**
+     * Build a signed-record envelope (v2) carrying the per-subject hash-chain
+     * fields.
+     *
+     * Identical to {@link signRecord} (self-issued: `issuer === subject`; same
+     * `ES256K-DER-SHA256` scheme) but `version` is `2` and the signed bytes
+     * additionally cover the chain fields:
+     *
+     * @param type - The record category.
+     * @param subject - The subject DID the record is about (also the issuer).
+     * @param record - The arbitrary record payload to attest to.
+     * @param chain - The hash-chain coordinates:
+     *   - `seq` — strictly-increasing sequence number for this subject's chain.
+     *   - `prev` — the `recordId` of the previous record, or `null` at genesis.
+     *   - `collection` + `rkey` — the AtProto-style record key.
+     *
+     * The caller is responsible for fetching the current chain head (so `seq` /
+     * `prev` are correct) before signing. Requires a stored identity; throws if
+     * none exists.
+     */
+    static async signRecordV2(type, subject, record, chain) {
+        const privateKey = await KeyManager.getPrivateKey();
+        if (!privateKey) {
+            throw new Error('No identity found. Please create or import an identity first.');
+        }
+        const { seq, prev, collection, rkey } = chain;
+        return signEnvelope({
+            version: 2,
+            type,
+            subject,
+            issuer: subject,
+            record,
+            issuedAt: Date.now(),
+            seq,
+            prev,
+            collection,
+            rkey,
+        }, privateKey);
+    }
+}
+export default SignatureService;

package/dist/esm/i18n/accountCategoryLabels.js

@@ -0,0 +1,37 @@
+import enUS from './locales/en-US.json' with { type: "json" };
+import { translate } from './index.js';
+/**
+ * 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
+ * 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
+ * build time, instead of a picker row that paints `accounts.accountCategory.<id>`
+ * at a user trying to choose one.
+ *
+ * That failure is not hypothetical. The screen previously wrote `t(key) || id`,
+ * whose author believed an unnamed id would degrade to its raw slug. It cannot:
+ * {@link translate} echoes the KEY when it resolves nothing, and a non-empty
+ * string is never falsy, so the `|| id` arm was unreachable and the output was
+ * the dotted key. A runtime fallback that cannot run is worse than none,
+ * because it reads as protection.
+ *
+ * Totality is over `ACCOUNT_CATEGORY_IDS`, which RETAINS withdrawn ids, so an
+ * account still carrying a retired category keeps rendering its name while no
+ * picker offers it again. Retired and unknown are different cases: only an id
+ * outside the union is unnameable, which is why this is keyed by
+ * `AccountCategoryId` and not by `string`.
+ */
+/**
+ * Module-scoped, NOT re-exported from the package index: the annotation is the
+ * whole job, and it does that job without being public API. It carries no
+ * `Object.freeze` and no `Readonly<>` for the same reason — those existed only
+ * to make an exported reference safe from a consumer's stray write, and there
+ * is no such consumer. Exported from the MODULE so its own test can name it.
+ */
+export const EN_ACCOUNT_CATEGORY_LABELS = enUS.accounts.accountCategory;
+export function accountCategoryLabel(locale, id) {
+    return translate(locale, `accounts.accountCategory.${id}`);
+}