@oxy.so/core 1.0.0

package/dist/cjs/crypto/identityMarker.js

@@ -0,0 +1,255 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_MARKER_STORAGE_KEY = void 0;
+exports.readIdentityMarker = readIdentityMarker;
+exports.writeIdentityMarker = writeIdentityMarker;
+exports.updateIdentityMarker = updateIdentityMarker;
+exports.clearIdentityMarker = clearIdentityMarker;
+const protocol_1 = require("@oxy.so/protocol");
+const logger_1 = require("../logger");
+const log = (0, logger_1.createLogger)('IdentityMarker');
+/**
+ * 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.
+ */
+exports.IDENTITY_MARKER_STORAGE_KEY = 'oxy_identity_marker_v1';
+/** RN detection identical to `DeviceManager` — chooses AsyncStorage vs localStorage. */
+function isReactNative() {
+    return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+}
+/**
+ * Resolve the platform KV store, or `null` when none is reachable (SSR, a
+ * sandboxed iframe whose `localStorage` getter throws, AsyncStorage not linked).
+ * A `null` store makes every marker operation a no-op that fails open.
+ */
+async function getStorage() {
+    try {
+        if (isReactNative()) {
+            // `loadAsyncStorage` is per-platform: the RN variant statically imports
+            // @react-native-async-storage/async-storage; the default variant throws
+            // (never reached here because of the `isReactNative()` gate).
+            const asyncStorageModule = await (0, protocol_1.loadAsyncStorage)();
+            const storage = asyncStorageModule.default;
+            return {
+                getItem: storage.getItem.bind(storage),
+                setItem: storage.setItem.bind(storage),
+                removeItem: storage.removeItem.bind(storage),
+            };
+        }
+        // Web: read `localStorage` through a try — merely ACCESSING it can throw a
+        // `SecurityError` in a sandboxed/cross-origin iframe.
+        if (typeof globalThis !== 'undefined') {
+            const ls = globalThis.localStorage;
+            if (ls) {
+                return {
+                    getItem: async (key) => ls.getItem(key),
+                    setItem: async (key, value) => {
+                        ls.setItem(key, value);
+                    },
+                    removeItem: async (key) => {
+                        ls.removeItem(key);
+                    },
+                };
+            }
+        }
+        return null;
+    }
+    catch (error) {
+        log.warn('Identity marker storage is unavailable', undefined, error);
+        return null;
+    }
+}
+/**
+ * Parse + shape-validate a stored blob. Returns `null` for anything that is not
+ * a well-formed {@link IdentityMarker} so a corrupt/foreign entry degrades to
+ * "no marker" rather than throwing.
+ */
+function deserialize(raw) {
+    if (!raw) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return null;
+    }
+    const candidate = parsed;
+    if (candidate.v !== 1) {
+        return null;
+    }
+    if (typeof candidate.publicKey !== 'string' || candidate.publicKey.length === 0) {
+        return null;
+    }
+    if (typeof candidate.createdAt !== 'number' || !Number.isFinite(candidate.createdAt)) {
+        return null;
+    }
+    const origin = candidate.origin;
+    if (origin !== 'create' && origin !== 'import' && origin !== 'restore' && origin !== 'backfill') {
+        return null;
+    }
+    const marker = {
+        v: 1,
+        publicKey: candidate.publicKey,
+        createdAt: candidate.createdAt,
+        origin,
+    };
+    if (typeof candidate.onboardingComplete === 'boolean') {
+        marker.onboardingComplete = candidate.onboardingComplete;
+    }
+    return marker;
+}
+/**
+ * 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.
+ */
+async function readIdentityMarker() {
+    const storage = await getStorage();
+    if (!storage) {
+        return null;
+    }
+    try {
+        return deserialize(await storage.getItem(exports.IDENTITY_MARKER_STORAGE_KEY));
+    }
+    catch (error) {
+        log.warn('Failed to read identity marker', undefined, error);
+        return 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.
+ */
+async function writeIdentityMarker(input) {
+    const storage = await getStorage();
+    if (!storage) {
+        return false;
+    }
+    const marker = {
+        v: 1,
+        publicKey: input.publicKey,
+        createdAt: input.createdAt ?? Date.now(),
+        origin: input.origin,
+    };
+    if (typeof input.onboardingComplete === 'boolean') {
+        marker.onboardingComplete = input.onboardingComplete;
+    }
+    try {
+        await storage.setItem(exports.IDENTITY_MARKER_STORAGE_KEY, JSON.stringify(marker));
+        return true;
+    }
+    catch (error) {
+        log.warn('Failed to write identity marker', undefined, error);
+        return false;
+    }
+}
+/**
+ * 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`.
+ */
+async function updateIdentityMarker(partial) {
+    const storage = await getStorage();
+    if (!storage) {
+        return false;
+    }
+    let existing = null;
+    try {
+        existing = deserialize(await storage.getItem(exports.IDENTITY_MARKER_STORAGE_KEY));
+    }
+    catch (error) {
+        log.warn('Failed to read identity marker before update', undefined, error);
+        existing = null;
+    }
+    if (!existing) {
+        if (typeof partial.publicKey === 'string' && partial.publicKey.length > 0 && partial.origin) {
+            return writeIdentityMarker({
+                publicKey: partial.publicKey,
+                origin: partial.origin,
+                createdAt: partial.createdAt,
+                onboardingComplete: partial.onboardingComplete,
+            });
+        }
+        return false;
+    }
+    const nextOnboarding = partial.onboardingComplete !== undefined ? partial.onboardingComplete : existing.onboardingComplete;
+    const next = {
+        v: 1,
+        publicKey: partial.publicKey ?? existing.publicKey,
+        createdAt: partial.createdAt ?? existing.createdAt,
+        origin: partial.origin ?? existing.origin,
+    };
+    if (typeof nextOnboarding === 'boolean') {
+        next.onboardingComplete = nextOnboarding;
+    }
+    try {
+        await storage.setItem(exports.IDENTITY_MARKER_STORAGE_KEY, JSON.stringify(next));
+        return true;
+    }
+    catch (error) {
+        log.warn('Failed to update identity marker', undefined, error);
+        return false;
+    }
+}
+/**
+ * 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.
+ */
+async function clearIdentityMarker() {
+    const storage = await getStorage();
+    if (!storage) {
+        return;
+    }
+    try {
+        await storage.removeItem(exports.IDENTITY_MARKER_STORAGE_KEY);
+    }
+    catch (error) {
+        log.warn('Failed to clear identity marker', undefined, error);
+    }
+}

package/dist/cjs/crypto/kdf.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * 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()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hkdfSha256 = hkdfSha256;
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha256_1 = require("@noble/hashes/sha256");
+/**
+ * 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.
+ */
+function hkdfSha256(ikm, salt, info, length) {
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new Error('hkdfSha256: length must be a positive integer');
+    }
+    // HKDF-Expand is defined for at most 255 * HashLen bytes of output.
+    if (length > 255 * 32) {
+        throw new Error('hkdfSha256: length must not exceed 8160 bytes (255 * 32)');
+    }
+    return (0, hkdf_1.hkdf)(sha256_1.sha256, ikm, salt, info, length);
+}