@oxy.so/protocol 1.0.0

package/src/chain/verify.ts

@@ -0,0 +1,102 @@
+/**
+ * Envelope verification — the ordered state machine that decides whether a
+ * signed-record envelope may be appended to its subject's chain.
+ *
+ * This is the engine that used to live, Oxy-specific, in
+ * `api/services/signedRecord.service.verifyEnvelope`. Every Oxy detail has been
+ * lifted out into the two injected collaborators:
+ *  - the {@link VerificationMethodResolver} owns "is this key authorized for this
+ *    issuer?" (self vs. custodial vs. untrusted),
+ *  - the {@link RecordStore} owns the monotonicity frontier + the chain head.
+ *
+ * The ordered checks (first failure wins):
+ *  1. **shape** — the base `signedRecordEnvelopeSchema` (open `type`, opaque
+ *     `record`). An app re-narrows `type` to its own set in its adapter.
+ *  2. **signature** — `verifyEnvelopeSignature` recomputes the canonical signing
+ *     input and checks the secp256k1 signature against the embedded `publicKey`.
+ *  3. **issuer authorization** — `resolver.resolve(subject)` + {@link isAuthorizedKey}.
+ *  4. **freshness** — `issuedAt` not beyond the tolerated clock skew.
+ *  5. **monotonicity** — `issuedAt` strictly newer than the store's latest record
+ *     for the same logical key (replay/rollback defence).
+ *  6. **continuity** — `checkContinuity` against the store's chain head (v1 skips).
+ *
+ * The `subject_mismatch` binding ("is the caller allowed to write for THIS
+ * subject?") is intentionally NOT here — it is an adapter-policy decision the
+ * caller makes before invoking the engine, not a property of the envelope.
+ */
+
+import { signedRecordEnvelopeSchema, type SignedRecordEnvelope } from '@oxy.so/contracts';
+import { verifyEnvelopeSignature } from '../envelope/sign';
+import { isAuthorizedKey, type VerificationMethodResolver } from '../identity/resolver';
+import { checkContinuity } from './continuity';
+import type { RecordStore } from './recordStore';
+import type { VerifyOutcome } from './types';
+
+/** Tunable verification options. */
+export interface VerifyOptions {
+  /** Tolerated forward clock skew for `issuedAt`, in ms. Default: 5 minutes. */
+  clockSkewMs?: number;
+  /** Override "now" (ms epoch) for deterministic tests. Default: `Date.now()`. */
+  now?: number;
+}
+
+/** Default tolerated forward clock skew for a record's `issuedAt` (5 minutes). */
+export const DEFAULT_CLOCK_SKEW_MS = 5 * 60 * 1000;
+
+/**
+ * Run the full verification state machine for `env` against the injected
+ * `store` (monotonicity + continuity) and `resolver` (issuer authorization).
+ * Returns a verdict; it never throws on a bad envelope.
+ */
+export async function verifyEnvelope(
+  store: RecordStore,
+  resolver: VerificationMethodResolver,
+  env: SignedRecordEnvelope,
+  opts: VerifyOptions = {},
+): Promise<VerifyOutcome> {
+  // 1. Base envelope shape (open `type`, `record` opaque). An app's adapter
+  //    re-narrows `type` to its own accepted set before/around this call.
+  if (!signedRecordEnvelopeSchema.safeParse(env).success) {
+    return { ok: false, reason: 'invalid_envelope' };
+  }
+
+  // 2. Signature is internally consistent with the embedded `publicKey`. Cheap,
+  //    pure crypto — rejected before any store/resolver I/O.
+  if (!(await verifyEnvelopeSignature(env))) {
+    return { ok: false, reason: 'bad_signature' };
+  }
+
+  // Enforce that v2 envelopes strictly contain required chain fields.
+  if (env.version === 2 && (typeof env.seq !== 'number' || typeof env.collection !== 'string' || typeof env.rkey !== 'string')) {
+    return { ok: false, reason: 'invalid_envelope' };
+  }
+
+  // 3. The signing key is an authorized writer for the issuer (self-issued ⇒ a
+  //    current VM of the subject; custodial ⇒ the custodial key; else untrusted).
+  const resolved = await resolver.resolve(env.subject);
+  const authorization = isAuthorizedKey(resolved, env);
+  if (!authorization.ok) {
+    return authorization;
+  }
+
+  // 4. Freshness: not issued beyond the tolerated forward clock skew.
+  const now = opts.now ?? Date.now();
+  const clockSkewMs = opts.clockSkewMs ?? DEFAULT_CLOCK_SKEW_MS;
+  if (env.issuedAt > now + clockSkewMs) {
+    return { ok: false, reason: 'issued_in_future' };
+  }
+
+  // 5. Monotonicity: strictly newer than the latest record for the same key.
+  const latestIssuedAt = await store.latestIssuedAtForKey(env.subject, env);
+  if (latestIssuedAt !== null && env.issuedAt <= latestIssuedAt) {
+    return { ok: false, reason: 'stale_issued_at' };
+  }
+
+  // 6. Continuity: the record extends the chain head by exactly one. Only v2 is
+  //    chained, so v1 never reads the head (it has no chain to extend).
+  if (env.version !== 2) {
+    return { ok: true };
+  }
+  const head = await store.getHead(env.subject);
+  return checkContinuity(head, env);
+}

package/src/envelope/canonicalJson.ts

@@ -0,0 +1,120 @@
+/**
+ * Canonical JSON (RFC 8785 / JCS-style) serialization.
+ *
+ * `canonicalize(value)` produces a deterministic string for any JSON-compatible
+ * value so that a client which SIGNS a record and a server which VERIFIES it
+ * agree byte-for-byte on the signing input — regardless of the order in which
+ * object keys happen to be written, how the value was deserialized, or which
+ * runtime built it.
+ *
+ * This is the load-bearing primitive for the protocol's signed records
+ * (`signEnvelope` + `verifyEnvelopeSignature`): every implementation imports
+ * THIS function from `@oxy.so/protocol`, so cross-implementation number/string
+ * formatting differences cannot cause a verify mismatch.
+ *
+ * Rules (the JSON Canonicalization Scheme subset we need):
+ *  - Objects: keys are sorted (ascending, by UTF-16 code unit — the default
+ *    `Array.prototype.sort` order) and serialized recursively. Properties whose
+ *    value is `undefined`, a function, or a symbol are OMITTED (matching
+ *    `JSON.stringify` object semantics).
+ *  - Arrays: element order is PRESERVED; `undefined`/function/symbol elements
+ *    serialize to `null` (matching `JSON.stringify` array semantics).
+ *  - `null`, booleans, strings, and finite numbers serialize via the standard
+ *    JSON representation.
+ *  - Values exposing a `toJSON()` method (e.g. `Date`) are replaced by its
+ *    result first, then serialized — so a `Date` and its ISO-string equivalent
+ *    canonicalize identically (the wire always carries the string form).
+ *  - Non-finite numbers (`NaN`, `Infinity`) and `bigint` are not part of the
+ *    JSON data model and throw, rather than silently producing `null`.
+ *
+ * Platform-agnostic — zero dependencies, no `require()`, no react/react-native/
+ * expo. Safe in the dual CJS + ESM build.
+ */
+
+/** Object exposing a `toJSON()` serialization hook (e.g. `Date`). */
+interface ToJsonable {
+  toJSON: () => unknown;
+}
+
+function hasToJSON(value: object): value is ToJsonable {
+  return typeof (value as { toJSON?: unknown }).toJSON === 'function';
+}
+
+/**
+ * Serialize a single value into its canonical JSON fragment. Recursive; called
+ * on each nested member. Object keys are sorted at every level.
+ */
+function serialize(value: unknown): string {
+  if (value === null) {
+    return 'null';
+  }
+
+  const valueType = typeof value;
+
+  if (valueType === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new Error('canonicalize: non-finite numbers cannot be serialized');
+    }
+    return JSON.stringify(value);
+  }
+
+  if (valueType === 'string' || valueType === 'boolean') {
+    return JSON.stringify(value);
+  }
+
+  if (valueType === 'bigint') {
+    throw new Error('canonicalize: bigint values cannot be serialized');
+  }
+
+  if (Array.isArray(value)) {
+    const items = value.map((item) => {
+      const itemType = typeof item;
+      // JSON array semantics: undefined / function / symbol become null so the
+      // element positions (and therefore the array length) are preserved.
+      if (item === undefined || itemType === 'function' || itemType === 'symbol') {
+        return 'null';
+      }
+      return serialize(item);
+    });
+    return `[${items.join(',')}]`;
+  }
+
+  if (valueType === 'object') {
+    const obj = value as object;
+    if (hasToJSON(obj)) {
+      return serialize(obj.toJSON());
+    }
+
+    const record = obj as Record<string, unknown>;
+    const parts: string[] = [];
+    for (const key of Object.keys(record).sort()) {
+      const member = record[key];
+      const memberType = typeof member;
+      // JSON object semantics: properties with undefined / function / symbol
+      // values are omitted entirely.
+      if (member === undefined || memberType === 'function' || memberType === 'symbol') {
+        continue;
+      }
+      parts.push(`${JSON.stringify(key)}:${serialize(member)}`);
+    }
+    return `{${parts.join(',')}}`;
+  }
+
+  // undefined / function / symbol at the top level have no JSON representation.
+  throw new Error(`canonicalize: cannot serialize a value of type ${valueType}`);
+}
+
+/**
+ * Produce the canonical JSON string for `value`.
+ *
+ * Deterministic: two structurally-equal values yield identical strings even if
+ * their object keys were written in different orders. Use this — never an
+ * ad-hoc `JSON.stringify` of a hand-sorted object — as the signing input for
+ * signed records, so client signing and server verification cannot drift.
+ *
+ * @throws if `value` (or any nested member used as the top-level/primitive)
+ *   contains a non-finite number or a `bigint`, which have no JSON form.
+ */
+export function canonicalize(value: unknown): string {
+  return serialize(value);
+}

package/src/envelope/recordId.ts

@@ -0,0 +1,63 @@
+/**
+ * Content hashing — SHA-256 + `recordId` (content address).
+ *
+ * `sha256` is the protocol's single platform-aware SHA-256: it uses
+ * `expo-crypto` on React Native, Node's built-in `crypto` on the server, and
+ * the Web Crypto API in the browser — always producing the same lowercase-hex
+ * digest. `computeRecordId` is `sha256(signedRecordSigningInput(fields))`: the
+ * content address that a record's chain `prev` pointer references.
+ */
+
+import { isReactNative, isNodeJS } from '../platform/platform';
+import { loadExpoCrypto, loadNodeCrypto } from '../platform/crypto';
+import { signedRecordSigningInput, type SignedRecordSigningFields } from './signingInput';
+
+/**
+ * Compute the SHA-256 hash of a string, returned as lowercase hex.
+ *
+ * Platform-aware: `expo-crypto` (RN) → Node `crypto` (server) → Web Crypto
+ * (browser). The three paths produce byte-identical digests, so a record
+ * hashed on a device and re-hashed on the server agree.
+ */
+export async function sha256(message: string): Promise<string> {
+  // In React Native, use expo-crypto
+  if (isReactNative()) {
+    const Crypto = await loadExpoCrypto();
+    return Crypto.digestStringAsync(
+      Crypto.CryptoDigestAlgorithm.SHA256,
+      message,
+    );
+  }
+
+  if (isNodeJS()) {
+    try {
+      const nodeCrypto = await loadNodeCrypto();
+      return nodeCrypto.createHash('sha256').update(message).digest('hex');
+    } catch {
+      // Node crypto failed to load — fall through to the Web Crypto API below,
+      // which is a correct, equivalent SHA-256 on any runtime that exposes it.
+    }
+  }
+
+  // Browser: use Web Crypto API
+  const encoder = new TextEncoder();
+  const data = encoder.encode(message);
+  const hashBuffer = await globalThis.crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Compute the `recordId` (content address) of a signed record: the SHA-256 hex
+ * digest of its canonical {@link signedRecordSigningInput}.
+ *
+ * Deterministic and stable across runtimes (it reuses the same canonicalization
+ * + SHA-256 the signature itself is built on). The recordId is what `prev`
+ * references in the per-subject hash chain, so every implementation MUST
+ * compute it identically — all call this function. It is taken over the SIGNING
+ * input (excluding `publicKey`/`signature`), so it is a pure content address of
+ * the record's meaning, independent of who signed.
+ */
+export async function computeRecordId(fields: SignedRecordSigningFields): Promise<string> {
+  return sha256(signedRecordSigningInput(fields));
+}

package/src/envelope/sign.ts

@@ -0,0 +1,86 @@
+/**
+ * Signing & verification — explicit-key crypto for signed-record envelopes.
+ *
+ * Stateless: every function takes the key material explicitly (no KeyManager,
+ * no secure storage). `@oxy.so/core` binds these to a device key; nodes and the
+ * API verify with them. The scheme is `ES256K-DER-SHA256` everywhere:
+ * secp256k1 over the SHA-256 of the canonical bytes, DER-encoded.
+ */
+
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import { signedRecordSigningInput, type SignedRecordSigningFields } from './signingInput';
+import { sha256 } from './recordId';
+import {
+  deriveSecp256k1PublicKey,
+  signSecp256k1Digest,
+  verifySecp256k1Digest,
+} from '../secp256k1';
+
+/** The one signature algorithm identifier the protocol emits. */
+const ALG = 'ES256K-DER-SHA256' as const;
+
+/**
+ * Sign an arbitrary message with an explicit private key.
+ *
+ * Hashes the message with SHA-256, then signs the digest with secp256k1,
+ * returning the DER-encoded hex signature. The low-level primitive behind both
+ * {@link signEnvelope} and `@oxy.so/core`'s device-key signing helpers.
+ */
+export async function signMessage(message: string, privateKeyHex: string): Promise<string> {
+  const digest = await sha256(message);
+  return signSecp256k1Digest(privateKeyHex, digest);
+}
+
+/**
+ * Verify a DER-encoded signature over a message against a public key.
+ *
+ * Returns `false` on any error (invalid signature, malformed key/signature,
+ * etc.) rather than throwing, so callers can treat verification as a boolean.
+ */
+export async function verifySignature(
+  message: string,
+  signature: string,
+  publicKeyHex: string,
+): Promise<boolean> {
+  try {
+    const digest = await sha256(message);
+    return verifySecp256k1Digest(publicKeyHex, digest, signature);
+  } catch {
+    // Malformed key / signature / input is not a valid signature.
+    return false;
+  }
+}
+
+/**
+ * Build a fully-signed {@link SignedRecordEnvelope} from its signing fields and
+ * an explicit private key.
+ *
+ * Computes the canonical {@link signedRecordSigningInput}, signs it
+ * (`ES256K-DER-SHA256`), and attaches the DERIVED `publicKey` (uncompressed
+ * hex — identical to `KeyManager`'s stored key for the same private key) plus
+ * the `alg`/`signature`. The signature covers every field EXCEPT
+ * `publicKey`/`signature`.
+ */
+export async function signEnvelope(
+  fields: SignedRecordSigningFields,
+  privateKeyHex: string,
+): Promise<SignedRecordEnvelope> {
+  const signingInput = signedRecordSigningInput(fields);
+  const signature = await signMessage(signingInput, privateKeyHex);
+  const publicKey = deriveSecp256k1PublicKey(privateKeyHex);
+  return { ...fields, publicKey, alg: ALG, signature };
+}
+
+/**
+ * Verify a signed-record envelope: recompute the canonical signing input from
+ * the envelope's own fields and check the signature against the envelope's
+ * `publicKey`.
+ *
+ * This confirms the signature is internally consistent with the embedded
+ * `publicKey`. It does NOT establish that `publicKey` is an authorized
+ * verification method for `subject` — that authorization check belongs to the
+ * server / node owner check.
+ */
+export async function verifyEnvelopeSignature(envelope: SignedRecordEnvelope): Promise<boolean> {
+  return verifySignature(signedRecordSigningInput(envelope), envelope.signature, envelope.publicKey);
+}

package/src/envelope/signingInput.ts

@@ -0,0 +1,48 @@
+/**
+ * Signed-record signing input — "what the signature covers".
+ *
+ * The single definition shared by every implementation (client signing and
+ * server verification), so a record signed by one and verified by another
+ * cannot drift.
+ */
+
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import { canonicalize } from './canonicalJson';
+
+/**
+ * The signing-input portion of a {@link SignedRecordEnvelope}: every field
+ * EXCEPT the `publicKey` and `signature`. Both the signer and the verifier
+ * canonicalize exactly these fields, so they agree on the bytes that the
+ * signature covers.
+ *
+ * The v2 chain fields (`seq`/`prev`/`collection`/`rkey`) are optional: a v1
+ * envelope omits them and is signed over only the base fields; a v2 envelope
+ * carries them and includes them in the signed bytes.
+ */
+export type SignedRecordSigningFields = Pick<
+  SignedRecordEnvelope,
+  'version' | 'type' | 'subject' | 'issuer' | 'record' | 'issuedAt'
+> &
+  Partial<Pick<SignedRecordEnvelope, 'seq' | 'prev' | 'collection' | 'rkey'>>;
+
+/**
+ * Compute the canonical signing input for a signed-record envelope.
+ *
+ * - **v1**: the canonical JSON of `{version, type, subject, issuer, record,
+ *   issuedAt}` — BYTE-IDENTICAL to the original scheme, so every signature
+ *   already in production keeps verifying.
+ * - **v2**: the canonical JSON additionally includes the hash-chain fields
+ *   `{seq, prev, collection, rkey}`. Because {@link canonicalize} sorts keys,
+ *   the on-the-wire field order is irrelevant; the resulting canonical key
+ *   order is `collection, issuedAt, issuer, prev, record, rkey, seq, subject,
+ *   type, version`. `prev` is `null` at genesis (serialized as `null`, not
+ *   omitted), so it is always part of the signed bytes.
+ */
+export function signedRecordSigningInput(fields: SignedRecordSigningFields): string {
+  const { version, type, subject, issuer, record, issuedAt } = fields;
+  if (version === 2) {
+    const { seq, prev, collection, rkey } = fields;
+    return canonicalize({ version, type, subject, issuer, record, issuedAt, seq, prev, collection, rkey });
+  }
+  return canonicalize({ version, type, subject, issuer, record, issuedAt });
+}

package/src/identity/resolver.ts

@@ -0,0 +1,90 @@
+/**
+ * Verification-method resolution — the injected authorization policy the chain
+ * engine consults to decide whether an envelope's signing key is allowed to
+ * write to the subject's chain.
+ *
+ * The engine is identity-agnostic: it does NOT know about Oxy DIDs, the `User`
+ * model, custodial keys, or any app's notion of "current key". It asks an
+ * injected {@link VerificationMethodResolver} to resolve a subject DID to its
+ * current verification methods (plus the optional custodial issuer that may sign
+ * provenance records ABOUT the subject), then applies the uniform authorization
+ * rule in {@link isAuthorizedKey}.
+ *
+ * This is what lets the SAME engine serve Oxy identity/civic records (where the
+ * resolver reads `User.publicKey`/`authMethods` and the Oxy custodial key), a
+ * self-hosted node (where the authority is a configured owner key), and Mention
+ * posts (subject VMs from the Oxy DID + a Mention custodial server key) — each
+ * supplies its own resolver; the decision logic lives here, once.
+ */
+
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import type { RejectionReason } from '../chain/types';
+
+/**
+ * The verification methods that may sign records on a subject's chain.
+ *
+ *  - `currentPublicKeys` — the subject's OWN current signing keys (self-issued
+ *    records: `issuer === subject`). Empty when the subject has no self-sovereign
+ *    key (e.g. a custodial-only account).
+ *  - `custodialIssuer` / `custodialPublicKey` — an optional custodial authority
+ *    that may sign provenance records ABOUT the subject (`issuer ===
+ *    custodialIssuer`), and the single public key it signs with. Both present or
+ *    both absent. The custodial public key is published (it lives in a DID
+ *    document), so a plain-equality comparison is sufficient — it is not a
+ *    secret.
+ */
+export interface ResolvedVerificationMethods {
+  currentPublicKeys: string[];
+  custodialIssuer?: string;
+  custodialPublicKey?: string;
+}
+
+export interface VerificationMethodResolver {
+  /**
+   * Resolve a subject DID to its current verification methods, or `null` when the
+   * subject is unknown / cannot be resolved (no key is then authorized).
+   */
+  resolve(subjectDid: string): Promise<ResolvedVerificationMethods | null>;
+}
+
+/** Verdict of the key-authorization decision (a subset of {@link RejectionReason}). */
+export type KeyAuthorization =
+  | { ok: true }
+  | { ok: false; reason: Extract<RejectionReason, 'public_key_not_a_current_verification_method' | 'untrusted_issuer'> };
+
+/**
+ * Decide whether `env`'s signing key (`env.publicKey`) is authorized for its
+ * `issuer`, given the subject's resolved verification methods:
+ *
+ *  - **Self-issued** (`issuer === subject`): the key MUST be one of the subject's
+ *    `currentPublicKeys`; otherwise `public_key_not_a_current_verification_method`.
+ *  - **Custodial** (`issuer === custodialIssuer`): the key MUST equal
+ *    `custodialPublicKey`; otherwise `public_key_not_a_current_verification_method`.
+ *  - **Any other issuer** (including an unresolvable subject): `untrusted_issuer`.
+ *
+ * The signature itself is checked separately (against `env.publicKey`), so this
+ * only decides whether that key is an authorized writer — it is not a trust
+ * shortcut.
+ */
+export function isAuthorizedKey(
+  resolved: ResolvedVerificationMethods | null,
+  env: SignedRecordEnvelope,
+): KeyAuthorization {
+  if (resolved !== null && env.issuer === env.subject) {
+    return resolved.currentPublicKeys.includes(env.publicKey)
+      ? { ok: true }
+      : { ok: false, reason: 'public_key_not_a_current_verification_method' };
+  }
+
+  if (
+    resolved !== null &&
+    resolved.custodialIssuer !== undefined &&
+    env.issuer === resolved.custodialIssuer
+  ) {
+    return resolved.custodialPublicKey !== undefined && env.publicKey === resolved.custodialPublicKey
+      ? { ok: true }
+      : { ok: false, reason: 'public_key_not_a_current_verification_method' };
+  }
+
+  return { ok: false, reason: 'untrusted_issuer' };
+}

package/src/index.ts

@@ -0,0 +1,101 @@
+/**
+ * @oxy.so/protocol — the app-agnostic Oxy Protocol base.
+ *
+ * The reusable substrate any Oxy app can use to decentralize its own content:
+ * the signed-record envelope grammar (canonical JSON, signing input, content
+ * address), explicit-key signing/verification, and the platform-aware crypto
+ * loaders. App-specific lexicons and the chain engine layer on top of this.
+ *
+ * Platform-agnostic root entry. Node-only pieces live under the `./node`
+ * subpath so they never enter React Native / web bundles.
+ */
+
+// ---------------------------------------------------------------------------
+// Envelope — canonical JSON, signing input, content address, signing/verify
+// ---------------------------------------------------------------------------
+export { canonicalize } from './envelope/canonicalJson';
+export { signedRecordSigningInput } from './envelope/signingInput';
+export type { SignedRecordSigningFields } from './envelope/signingInput';
+export { sha256, computeRecordId } from './envelope/recordId';
+export {
+  signMessage,
+  verifySignature,
+  signEnvelope,
+  verifyEnvelopeSignature,
+} from './envelope/sign';
+
+// ---------------------------------------------------------------------------
+// Chain — per-subject hash-chain engine over an injected RecordStore + resolver
+// ---------------------------------------------------------------------------
+export type {
+  ChainHead,
+  RejectionReason,
+  VerifyOutcome,
+  AppendOutcome,
+} from './chain/types';
+export { UNCHAINED_SEQ } from './chain/types';
+export { checkContinuity } from './chain/continuity';
+export type { RecordStore, BlobStore } from './chain/recordStore';
+export { verifyEnvelope, DEFAULT_CLOCK_SKEW_MS } from './chain/verify';
+export type { VerifyOptions } from './chain/verify';
+export { verifyAndAppend } from './chain/engine';
+
+// ---------------------------------------------------------------------------
+// Transparency — Merkle commitment over chain heads + co-signable checkpoints
+// ---------------------------------------------------------------------------
+export {
+  EMPTY_TRANSPARENCY_ROOT,
+  transparencyLeafHash,
+  buildTransparencyTree,
+  buildTransparencyTreeFromHeads,
+  inclusionProof,
+  verifyInclusionProof,
+} from './transparency/tree';
+export type {
+  TransparencyHeadEntry,
+  TransparencyTree,
+  TransparencyTreeFromHeads,
+  InclusionProofCheck,
+} from './transparency/tree';
+export {
+  checkpointSigningInput,
+  checkpointHash,
+  signCheckpoint,
+  verifyCheckpointSignature,
+} from './transparency/checkpoint';
+export type {
+  TransparencyCheckpointFields,
+  TransparencyCheckpointSignature,
+} from './transparency/checkpoint';
+
+// ---------------------------------------------------------------------------
+// Identity — injected verification-method resolution + authorization rule
+// ---------------------------------------------------------------------------
+export { isAuthorizedKey } from './identity/resolver';
+export type {
+  VerificationMethodResolver,
+  ResolvedVerificationMethods,
+  KeyAuthorization,
+} from './identity/resolver';
+
+// ---------------------------------------------------------------------------
+// Platform — runtime predicates + lazy crypto/storage loaders
+// ---------------------------------------------------------------------------
+export { isReactNative, isNodeJS } from './platform/platform';
+export {
+  loadNodeCrypto,
+  loadExpoCrypto,
+  loadSecureStore,
+  loadAsyncStorage,
+  getRandomBytesRN,
+  loadSharedIdentityBridge,
+} from './platform/crypto';
+
+// ---------------------------------------------------------------------------
+// Platform types — structural interfaces for Expo modules.
+//
+// Exported so @oxy.so/core and other consumers can type their own wrappers
+// without importing `typeof import('expo-crypto')` / `typeof import('expo-secure-store')`
+// (which would trigger NodeNext type pollution in server packages).
+// ---------------------------------------------------------------------------
+export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './platform/expoTypes';