@oxy.so/protocol 1.0.0

package/dist/types/chain/continuity.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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).
+ */
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import type { ChainHead, VerifyOutcome } from './types';
+/**
+ * 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 declare function checkContinuity(head: ChainHead | null, env: SignedRecordEnvelope): VerifyOutcome;

package/dist/types/chain/engine.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import type { VerificationMethodResolver } from '../identity/resolver';
+import { type VerifyOptions } from './verify';
+import type { RecordStore } from './recordStore';
+import type { AppendOutcome } from './types';
+/**
+ * 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 declare function verifyAndAppend(store: RecordStore, resolver: VerificationMethodResolver, env: SignedRecordEnvelope, opts?: VerifyOptions): Promise<AppendOutcome>;

package/dist/types/chain/recordStore.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import type { AppendOutcome, ChainHead } from './types';
+export interface RecordStore {
+    /** The subject's chain head, or `null` when the subject has no chain yet. */
+    getHead(subject: string): Promise<ChainHead | null>;
+    /**
+     * Atomically persist a verified envelope and advance the subject's chain.
+     *
+     * `recordId` is the engine-computed content address (`computeRecordId(env)`).
+     * Implementations MUST surface a duplicate-key collision as `chain_conflict`
+     * (see the concurrency contract above). v1 envelopes (no chain coordinates)
+     * are stored without advancing a chain and SHOULD report `seq: -1`.
+     */
+    append(subject: string, env: SignedRecordEnvelope, recordId: string): Promise<AppendOutcome>;
+    /**
+     * The ordered slice of the subject's chain with `seq > sinceSeq`, ascending by
+     * `seq`, capped at `limit`. Only chained (v2) records have a `seq`, so v1 rows
+     * are naturally excluded. Pass `sinceSeq = -1` to start from genesis.
+     */
+    getLogSince(subject: string, sinceSeq: number, limit: number): Promise<SignedRecordEnvelope[]>;
+    /**
+     * Resolve a `recordId` cursor to its chain `seq` (so a puller resumes from the
+     * last record it ingested), or `null` when no such record exists.
+     */
+    resolveCursorSeq(subject: string, recordId: string): Promise<number | null>;
+    /**
+     * The latest verified envelope for an AtProto-style `(collection, rkey)` key —
+     * the materialized "current" value (last-writer-wins by chain order), or
+     * `null` when no record exists for that key.
+     */
+    materializeCurrent(subject: string, collection: string, rkey: string): Promise<SignedRecordEnvelope | null>;
+    /**
+     * The `issuedAt` of the latest stored record for the envelope's LOGICAL key —
+     * the monotonicity frontier the engine compares against (replay/rollback
+     * defence). Scoping is the store's policy:
+     *  - v2: per record key (`collection`, `rkey`) — last-writer-wins for THAT key.
+     *  - v1: per `type` (the legacy identity/profile singletons).
+     *
+     * Returns `null` when there is no prior record (the record is the first of its
+     * key, so any `issuedAt` is acceptable).
+     */
+    latestIssuedAtForKey(subject: string, env: SignedRecordEnvelope): Promise<number | null>;
+}
+/**
+ * Content-addressed blob storage — the bytes a record's blob refs point at,
+ * keyed by their SHA-256 (`sha256`) content address.
+ *
+ * Separate from {@link RecordStore} because not every app stores blobs in the
+ * same place a record lives (oxy-api identity records carry no blobs; a node
+ * pins them; Mention rehosts to the Oxy CDN). `Uint8Array` rather than Node's
+ * `Buffer` so the interface stays platform-agnostic.
+ */
+export interface BlobStore {
+    /**
+     * Pin `bytes` under their content address `hash`. Implementations MUST validate
+     * that `bytes` actually hash to `hash`, and SHOULD be idempotent (re-pinning
+     * the same hash is a no-op).
+     */
+    putBlob(hash: string, bytes: Uint8Array): Promise<void>;
+    /** The bytes of a pinned blob, or `null` when absent. */
+    getBlob(hash: string): Promise<Uint8Array | null>;
+}

package/dist/types/chain/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 O(1) head pointer of a subject's chain.
+ *
+ * `headRecordId` is the content address of the latest record (`null` only on the
+ * "no chain yet" wire shape); `seq` is its sequence number; `recordCount` is the
+ * total appended so far. A store returns `null` (not a `ChainHead`) when the
+ * subject has no chain — the engine treats both `null` and a `headRecordId:null`
+ * head as "no chain".
+ */
+export interface ChainHead {
+    headRecordId: string | null;
+    seq: number;
+    recordCount: number;
+}
+/**
+ * Every way verifying or appending a signed record can be rejected — stable,
+ * machine-readable, and the ONE consolidated union across the protocol.
+ *
+ *  - `invalid_envelope` — the envelope failed the base schema shape.
+ *  - `subject_mismatch` — the envelope's `subject` is not who the caller is
+ *    authorized to write for (an adapter-policy binding, surfaced here so a
+ *    store/adapter can report it on the same channel).
+ *  - `public_key_not_a_current_verification_method` — the issuer is recognized
+ *    (self or custodial) but the signing key is not its current key.
+ *  - `bad_signature` — the signature does not verify against the embedded key.
+ *  - `issued_in_future` — `issuedAt` is beyond the tolerated clock skew.
+ *  - `stale_issued_at` — `issuedAt` is not strictly newer than the latest record
+ *    for the same logical key (replay/rollback defence).
+ *  - `chain_gap` — a non-genesis record claims to extend a chain that has no head.
+ *  - `chain_fork` — `prev` does not match the current head (or a re-genesis).
+ *  - `bad_seq` — `seq` is not exactly `head.seq + 1`.
+ *  - `chain_conflict` — a concurrent writer already took this `seq` (the store's
+ *    unique-index backstop, surfaced from a duplicate-key error).
+ *  - `untrusted_issuer` — the `issuer` is neither the subject nor a recognized
+ *    custodial issuer.
+ */
+export type RejectionReason = 'invalid_envelope' | 'subject_mismatch' | 'public_key_not_a_current_verification_method' | 'bad_signature' | 'issued_in_future' | 'stale_issued_at' | 'chain_gap' | 'chain_fork' | 'bad_seq' | 'chain_conflict' | 'untrusted_issuer';
+/** Verdict of verifying an envelope WITHOUT persisting it. */
+export type VerifyOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    reason: RejectionReason;
+};
+/**
+ * Outcome of appending a verified envelope to a chain.
+ *
+ * On success it carries the record's content address (`recordId`) and its chain
+ * `seq` (`-1` for an unchained v1 record, which has no sequence). On failure it
+ * carries the {@link RejectionReason} (a continuity violation or the store's
+ * `chain_conflict` backstop).
+ */
+export type AppendOutcome = {
+    ok: true;
+    recordId: string;
+    seq: number;
+} | {
+    ok: false;
+    reason: RejectionReason;
+};
+/** The `seq` reported for a v1 (unchained) append — it has no sequence. */
+export declare const UNCHAINED_SEQ = -1;

package/dist/types/chain/verify.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 { type SignedRecordEnvelope } from '@oxy.so/contracts';
+import { type VerificationMethodResolver } from '../identity/resolver';
+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 declare const DEFAULT_CLOCK_SKEW_MS: number;
+/**
+ * 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 declare function verifyEnvelope(store: RecordStore, resolver: VerificationMethodResolver, env: SignedRecordEnvelope, opts?: VerifyOptions): Promise<VerifyOutcome>;

package/dist/types/envelope/canonicalJson.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function canonicalize(value: unknown): string;

package/dist/types/envelope/recordId.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { 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 declare function sha256(message: string): Promise<string>;
+/**
+ * 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 declare function computeRecordId(fields: SignedRecordSigningFields): Promise<string>;

package/dist/types/envelope/sign.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 { type SignedRecordSigningFields } from './signingInput';
+/**
+ * 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 declare function signMessage(message: string, privateKeyHex: string): Promise<string>;
+/**
+ * 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 declare function verifySignature(message: string, signature: string, publicKeyHex: string): Promise<boolean>;
+/**
+ * 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 declare function signEnvelope(fields: SignedRecordSigningFields, privateKeyHex: string): Promise<SignedRecordEnvelope>;
+/**
+ * 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 declare function verifyEnvelopeSignature(envelope: SignedRecordEnvelope): Promise<boolean>;

package/dist/types/envelope/signingInput.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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';
+/**
+ * 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 declare function signedRecordSigningInput(fields: SignedRecordSigningFields): string;

package/dist/types/identity/resolver.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 declare function isAuthorizedKey(resolved: ResolvedVerificationMethods | null, env: SignedRecordEnvelope): KeyAuthorization;

package/dist/types/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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.
+ */
+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';
+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';
+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';
+export { isAuthorizedKey } from './identity/resolver';
+export type { VerificationMethodResolver, ResolvedVerificationMethods, KeyAuthorization, } from './identity/resolver';
+export { isReactNative, isNodeJS } from './platform/platform';
+export { loadNodeCrypto, loadExpoCrypto, loadSecureStore, loadAsyncStorage, getRandomBytesRN, loadSharedIdentityBridge, } from './platform/crypto';
+export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './platform/expoTypes';

package/dist/types/node/constants.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 declare const PROTOCOL_VERSION: "oxy-node/1";
+/** Default well-known manifest path (the existing `@oxy.so/node` value). */
+export declare const DEFAULT_WELL_KNOWN_PATH = "/.well-known/oxy-node.json";
+/** Default DID-document service-type label advertised by a node deployment. */
+export declare 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 declare const DEFAULT_APP_NAMESPACE = "app.oxy";
+/** Default HTTP port when the port env var is unset (always overridable). */
+export declare const DEFAULT_PORT = 4000;
+/** Default and maximum number of log entries returned by `GET /oxy/log`. */
+export declare const DEFAULT_LOG_LIMIT = 100;
+export declare const MAX_LOG_LIMIT = 500;
+/** Default upper bound on a single pinned blob's size when unset (25 MiB). */
+export declare const DEFAULT_MAX_BLOB_BYTES: number;
+/** Maximum number of envelopes accepted in one `POST /sync/push` batch. */
+export declare const MAX_SYNC_BATCH = 200;
+/** Body-size ceiling for JSON request bodies (`/records`, `/sync/push`). */
+export declare const JSON_BODY_LIMIT = "5mb";
+/** HTTP headers carrying an owner-signed action authorization (blob pins). */
+export declare const OWNER_AUTH_HEADERS: {
+    readonly publicKey: "x-oxy-node-public-key";
+    readonly signature: "x-oxy-node-signature";
+    readonly 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 declare const OWNER_AUTH_MAX_AGE_MS: number;
+/** Operating modes a node can advertise. */
+export declare const NODE_MODES: readonly ["self-hosted", "managed"];
+export type NodeMode = (typeof NODE_MODES)[number];
+/** The node operation an owner can authorize with a signed header. */
+export declare const OWNER_ACTION_BLOB_PIN: "blob-pin";
+/** A 32-byte (64 hex char) lowercase SHA-256 digest, used as the blob address. */
+export declare const SHA256_HEX: RegExp;
+/** Chain head endpoint (`GET`). */
+export declare const NODE_HEAD_PATH = "/oxy/head";
+/** Ordered log endpoint (`GET ?since=&limit=`). */
+export declare const NODE_LOG_PATH = "/oxy/log";
+/** Single-record write endpoint (`POST`, owner-signed envelope). */
+export declare const NODE_RECORDS_PATH = "/records";
+/** Batch push endpoint (`POST`, owner-signed envelopes). */
+export declare const NODE_SYNC_PUSH_PATH = "/sync/push";
+/** Content-addressed blob endpoint prefix (`GET|PUT /blobs/:hash`). */
+export declare const NODE_BLOBS_PATH = "/blobs";
+/** Default time-to-first-byte deadline for a NodeClient request (ms). */
+export declare const DEFAULT_CLIENT_TIMEOUT_MS = 8000;
+/** Default redirect budget for a NodeClient request (each re-validated upstream). */
+export declare const DEFAULT_CLIENT_MAX_REDIRECTS = 1;
+/** Default bounded read for a `/oxy/head` response (tiny JSON). */
+export declare const DEFAULT_HEAD_MAX_BYTES: number;
+/** Default bounded read for a `/oxy/log` page response. */
+export declare const DEFAULT_LOG_MAX_BYTES: number;
+/** Default bounded read for a small JSON write response (`/records`, blob pin). */
+export declare const DEFAULT_WRITE_RESPONSE_MAX_BYTES: number;
+/** Default bounded read for a fetched `<did>.json` document. */
+export declare const DEFAULT_DID_DOC_MAX_BYTES: number;