@oxy.so/protocol 1.0.0

package/dist/esm/chain/continuity.js

@@ -0,0 +1,51 @@
+/**
+ * Chain continuity — the pure "does this record extend the head by exactly one?"
+ * check, with NO storage or crypto dependency.
+ *
+ * This is the single definition of continuity that used to be duplicated in
+ * oxy-api (`verifyChainContinuity`) and the node store (`appendTxn`). The engine
+ * calls it with the head it read from the injected store; a store MAY call it
+ * again inside its atomic append, but the unique-index backstop (surfaced as
+ * `chain_conflict`) is the real race guard.
+ *
+ * v1 envelopes have no chain coordinates, so they always pass (the caller does
+ * not advance a chain for them).
+ */
+/**
+ * True when `head` represents an actual existing chain (as opposed to `null` or
+ * the "no chain yet" sentinel head a store may return).
+ */
+function hasChain(head) {
+    return head !== null && head.headRecordId !== null && head.seq >= 0;
+}
+/**
+ * Check that `env` validly extends `head`:
+ *
+ *  - **v1** (no chain coordinates): always `{ ok: true }` — v1 records are not
+ *    chained.
+ *  - **no head** (genesis position): only a genesis (`seq === 0`, `prev` null)
+ *    is accepted; anything else is `chain_gap` (it claims to extend a chain that
+ *    does not exist).
+ *  - **head exists**: `env.prev` MUST equal `head.headRecordId` (else
+ *    `chain_fork`, which also covers a re-genesis whose `prev` is `null`), and
+ *    `env.seq` MUST equal `head.seq + 1` (else `bad_seq`).
+ */
+export function checkContinuity(head, env) {
+    if (env.version !== 2) {
+        return { ok: true };
+    }
+    const isGenesis = env.seq === 0 && (env.prev === null || env.prev === undefined);
+    if (!hasChain(head)) {
+        if (!isGenesis) {
+            return { ok: false, reason: 'chain_gap' };
+        }
+        return { ok: true };
+    }
+    if (env.prev !== head.headRecordId) {
+        return { ok: false, reason: 'chain_fork' };
+    }
+    if (env.seq !== head.seq + 1) {
+        return { ok: false, reason: 'bad_seq' };
+    }
+    return { ok: true };
+}

package/dist/esm/chain/engine.js

@@ -0,0 +1,31 @@
+/**
+ * Chain engine — verify-then-append orchestration.
+ *
+ * The one entry point an app's adapter calls to publish a record: it runs the
+ * full {@link verifyEnvelope} state machine, computes the content address
+ * (`recordId`), and hands the verified envelope to the injected
+ * {@link RecordStore} to persist atomically. The store owns the durable
+ * concurrency backstop (`chain_conflict` on a unique-index collision); the
+ * engine owns the verification + ordering policy.
+ *
+ * Storage and identity are both injected, so the engine has zero knowledge of
+ * Mongo/SQLite, Oxy DIDs, or any app's lexicon — exactly what makes it reusable.
+ */
+import { computeRecordId } from '../envelope/recordId.js';
+import { verifyEnvelope } from './verify.js';
+/**
+ * Verify `env` and, if it passes, append it to the subject's chain.
+ *
+ * On a verification failure the rejection is returned WITHOUT touching the store.
+ * On success the (engine-computed) `recordId` is passed to `store.append`, whose
+ * own outcome — including the `chain_conflict` backstop on a concurrent-writer
+ * collision — is returned verbatim.
+ */
+export async function verifyAndAppend(store, resolver, env, opts = {}) {
+    const verification = await verifyEnvelope(store, resolver, env, opts);
+    if (!verification.ok) {
+        return verification;
+    }
+    const recordId = await computeRecordId(env);
+    return store.append(env.subject, env, recordId);
+}

package/dist/esm/chain/recordStore.js

@@ -0,0 +1,24 @@
+/**
+ * Storage interfaces — the injected persistence the chain engine drives.
+ *
+ * The engine ({@link ./verify}, {@link ./engine}) is storage-agnostic: it owns
+ * the verification state machine and continuity logic, and delegates EVERY read
+ * and write to an injected {@link RecordStore}. An app supplies a store over its
+ * own backend (oxy-api over Mongo `SignedRecord`/`RepoHead`, a node over SQLite,
+ * Mention over its own Mongo) without the engine knowing anything Oxy- or
+ * app-specific.
+ *
+ * All methods are **subject-keyed**: `subject` is the chain's subject DID
+ * (`env.subject`). A store maps that DID to its own primary key (e.g. an Oxy
+ * userId) internally; the engine never sees that mapping.
+ *
+ * ## Concurrency contract
+ *
+ * `append` MUST be atomic (record insert + head advance in one unit) and MUST
+ * translate a duplicate-key collision on the unique `(subject, seq)` /
+ * `recordId` index — i.e. a concurrent writer that already took this `seq` — into
+ * `{ ok: false, reason: 'chain_conflict' }` (Mongo E11000 / SQLite
+ * `SQLITE_CONSTRAINT`). That is the real multi-writer race guard; the engine's
+ * pre-append continuity check is only the fast-path rejection.
+ */
+export {};

package/dist/esm/chain/types.js

@@ -0,0 +1,19 @@
+/**
+ * Chain engine types — the per-subject hash-chain vocabulary.
+ *
+ * A "chain" is a single signer's append-only log of signed-record envelopes
+ * ("personal blockchain": one signer, no consensus/mining), ordered by a
+ * strictly-increasing `seq` with each record's `prev` pointing at the content
+ * address (`recordId`) of the one before it. These types are storage-agnostic:
+ * the engine ({@link ./verify}, {@link ./engine}) drives them over an injected
+ * {@link ./recordStore.RecordStore}, and any app (Oxy identity/civic/node,
+ * Mention posts, …) supplies its own store + resolver.
+ *
+ * The {@link RejectionReason} union is the SINGLE source of truth for every way
+ * an append can fail — it consolidates what used to be three divergent copies
+ * (oxy-api's `EnvelopeRejectionReason`, the node store's `AppendOutcome.reason`,
+ * and the node verifier's `VerifyRejectionReason`). The exact strings match the
+ * ones oxy-api returns today, so API responses are byte-for-byte unchanged.
+ */
+/** The `seq` reported for a v1 (unchained) append — it has no sequence. */
+export const UNCHAINED_SEQ = -1;

package/dist/esm/chain/verify.js

@@ -0,0 +1,78 @@
+/**
+ * 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 } from '@oxy.so/contracts';
+import { verifyEnvelopeSignature } from '../envelope/sign.js';
+import { isAuthorizedKey } from '../identity/resolver.js';
+import { checkContinuity } from './continuity.js';
+/** 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, resolver, env, opts = {}) {
+    // 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/dist/esm/envelope/canonicalJson.js

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ */
+function hasToJSON(value) {
+    return typeof value.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) {
+    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;
+        if (hasToJSON(obj)) {
+            return serialize(obj.toJSON());
+        }
+        const record = obj;
+        const parts = [];
+        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) {
+    return serialize(value);
+}

package/dist/esm/envelope/recordId.js

@@ -0,0 +1,56 @@
+/**
+ * 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.js';
+import { loadExpoCrypto, loadNodeCrypto } from '../platform/crypto.js';
+import { signedRecordSigningInput } from './signingInput.js';
+/**
+ * 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) {
+    // 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) {
+    return sha256(signedRecordSigningInput(fields));
+}

package/dist/esm/envelope/sign.js

@@ -0,0 +1,69 @@
+/**
+ * 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 { signedRecordSigningInput } from './signingInput.js';
+import { sha256 } from './recordId.js';
+import { deriveSecp256k1PublicKey, signSecp256k1Digest, verifySecp256k1Digest, } from '../secp256k1.js';
+/** The one signature algorithm identifier the protocol emits. */
+const ALG = 'ES256K-DER-SHA256';
+/**
+ * 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, privateKeyHex) {
+    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, signature, publicKeyHex) {
+    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, privateKeyHex) {
+    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) {
+    return verifySignature(signedRecordSigningInput(envelope), envelope.signature, envelope.publicKey);
+}

package/dist/esm/envelope/signingInput.js

@@ -0,0 +1,29 @@
+/**
+ * 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 { canonicalize } from './canonicalJson.js';
+/**
+ * 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) {
+    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/dist/esm/identity/resolver.js

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+/**
+ * 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, env) {
+    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/dist/esm/index.js

@@ -0,0 +1,36 @@
+/**
+ * @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.js';
+export { signedRecordSigningInput } from './envelope/signingInput.js';
+export { sha256, computeRecordId } from './envelope/recordId.js';
+export { signMessage, verifySignature, signEnvelope, verifyEnvelopeSignature, } from './envelope/sign.js';
+export { UNCHAINED_SEQ } from './chain/types.js';
+export { checkContinuity } from './chain/continuity.js';
+export { verifyEnvelope, DEFAULT_CLOCK_SKEW_MS } from './chain/verify.js';
+export { verifyAndAppend } from './chain/engine.js';
+// ---------------------------------------------------------------------------
+// Transparency — Merkle commitment over chain heads + co-signable checkpoints
+// ---------------------------------------------------------------------------
+export { EMPTY_TRANSPARENCY_ROOT, transparencyLeafHash, buildTransparencyTree, buildTransparencyTreeFromHeads, inclusionProof, verifyInclusionProof, } from './transparency/tree.js';
+export { checkpointSigningInput, checkpointHash, signCheckpoint, verifyCheckpointSignature, } from './transparency/checkpoint.js';
+// ---------------------------------------------------------------------------
+// Identity — injected verification-method resolution + authorization rule
+// ---------------------------------------------------------------------------
+export { isAuthorizedKey } from './identity/resolver.js';
+// ---------------------------------------------------------------------------
+// Platform — runtime predicates + lazy crypto/storage loaders
+// ---------------------------------------------------------------------------
+export { isReactNative, isNodeJS } from './platform/platform.js';
+export { loadNodeCrypto, loadExpoCrypto, loadSecureStore, loadAsyncStorage, getRandomBytesRN, loadSharedIdentityBridge, } from './platform/crypto.js';

package/dist/esm/node/constants.js

@@ -0,0 +1,82 @@
+/**
+ * Node-protocol shape constants — the wire-level contract of an Oxy-protocol
+ * data node, shared by the generic node app factory ({@link ./nodeApp}), the
+ * HTTP {@link ./nodeClient.NodeClient}, and any app's node deployment
+ * (`@oxy.so/node`, a future `mention-node`).
+ *
+ * These were previously hardcoded inside `@oxy.so/node`; they live here so the
+ * SAME values drive a server and a client without either side re-declaring (and
+ * drifting) the contract. Deployment-specific knobs (owner key, port, data dir)
+ * are still resolved per-deployment from the environment — only the protocol's
+ * own shape constants live here.
+ */
+/**
+ * The node-protocol version advertised at the well-known manifest. Bumped only
+ * on a breaking change to the wire shape of the log / head / record APIs. This
+ * is the DEFAULT `protocolId` a deployment advertises (overridable per app).
+ */
+export const PROTOCOL_VERSION = 'oxy-node/1';
+/** Default well-known manifest path (the existing `@oxy.so/node` value). */
+export const DEFAULT_WELL_KNOWN_PATH = '/.well-known/oxy-node.json';
+/** Default DID-document service-type label advertised by a node deployment. */
+export const DEFAULT_SERVICE_TYPE = 'OxyPersonalDataNode';
+/**
+ * Default application namespace a node deployment serves. The records a node
+ * stores all live under this namespace (e.g. `app.oxy.*`); a `collections`
+ * allowlist (when set) MUST be within it.
+ */
+export const DEFAULT_APP_NAMESPACE = 'app.oxy';
+/** Default HTTP port when the port env var is unset (always overridable). */
+export const DEFAULT_PORT = 4000;
+/** Default and maximum number of log entries returned by `GET /oxy/log`. */
+export const DEFAULT_LOG_LIMIT = 100;
+export const MAX_LOG_LIMIT = 500;
+/** Default upper bound on a single pinned blob's size when unset (25 MiB). */
+export const DEFAULT_MAX_BLOB_BYTES = 25 * 1024 * 1024;
+/** Maximum number of envelopes accepted in one `POST /sync/push` batch. */
+export const MAX_SYNC_BATCH = 200;
+/** Body-size ceiling for JSON request bodies (`/records`, `/sync/push`). */
+export const JSON_BODY_LIMIT = '5mb';
+/** HTTP headers carrying an owner-signed action authorization (blob pins). */
+export const OWNER_AUTH_HEADERS = {
+    publicKey: 'x-oxy-node-public-key',
+    signature: 'x-oxy-node-signature',
+    timestamp: 'x-oxy-node-timestamp',
+};
+/**
+ * Freshness window for an owner-signed action (e.g. a blob pin). A signed
+ * authorization header older/newer than this (accounting for clock skew) is
+ * rejected, bounding replay of a captured pin authorization.
+ */
+export const OWNER_AUTH_MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes
+/** Operating modes a node can advertise. */
+export const NODE_MODES = ['self-hosted', 'managed'];
+/** The node operation an owner can authorize with a signed header. */
+export const OWNER_ACTION_BLOB_PIN = 'blob-pin';
+/** A 32-byte (64 hex char) lowercase SHA-256 digest, used as the blob address. */
+export const SHA256_HEX = /^[0-9a-f]{64}$/;
+/* -------------------------------------------------------------------------- */
+/*  HTTP NodeClient — the node-facing routes a client drives                  */
+/* -------------------------------------------------------------------------- */
+/** Chain head endpoint (`GET`). */
+export const NODE_HEAD_PATH = '/oxy/head';
+/** Ordered log endpoint (`GET ?since=&limit=`). */
+export const NODE_LOG_PATH = '/oxy/log';
+/** Single-record write endpoint (`POST`, owner-signed envelope). */
+export const NODE_RECORDS_PATH = '/records';
+/** Batch push endpoint (`POST`, owner-signed envelopes). */
+export const NODE_SYNC_PUSH_PATH = '/sync/push';
+/** Content-addressed blob endpoint prefix (`GET|PUT /blobs/:hash`). */
+export const NODE_BLOBS_PATH = '/blobs';
+/** Default time-to-first-byte deadline for a NodeClient request (ms). */
+export const DEFAULT_CLIENT_TIMEOUT_MS = 8000;
+/** Default redirect budget for a NodeClient request (each re-validated upstream). */
+export const DEFAULT_CLIENT_MAX_REDIRECTS = 1;
+/** Default bounded read for a `/oxy/head` response (tiny JSON). */
+export const DEFAULT_HEAD_MAX_BYTES = 64 * 1024;
+/** Default bounded read for a `/oxy/log` page response. */
+export const DEFAULT_LOG_MAX_BYTES = 2 * 1024 * 1024;
+/** Default bounded read for a small JSON write response (`/records`, blob pin). */
+export const DEFAULT_WRITE_RESPONSE_MAX_BYTES = 64 * 1024;
+/** Default bounded read for a fetched `<did>.json` document. */
+export const DEFAULT_DID_DOC_MAX_BYTES = 256 * 1024;