@mida-context/sdk 0.1.0

package/dist/types/api/chain-budget.d.ts

@@ -0,0 +1,61 @@
+import type { Address, AgentRecord, Hex } from "../protocol/index.js";
+import { RegistryReader } from "./chain-views.js";
+import type { CapabilityView, ContextRecordView } from "./chain-views.js";
+/**
+ * One chain read costs one platform subrequest. Cloudflare's Workers FREE plan allows 50 per
+ * invocation (check the current Workers limits page), so a request's Monad budget is 30 — the rest
+ * of the allowance covers D1, the rate-limit binding and logging inside the same invocation. The
+ * same cap is enforced in the self-hosted app: a bounded request is a request that can be reasoned
+ * about, whatever serves it.
+ */
+export declare const MAX_CHAIN_READS_PER_REQUEST = 30;
+/** Thrown the moment a request tries to spend one chain read more than its per-request budget. */
+export declare class ChainReadBudgetExceeded extends Error {
+    readonly code: "CHAIN_READ_BUDGET_EXHAUSTED";
+    constructor(message?: string);
+}
+export declare function isChainReadBudgetExceeded(value: unknown): value is ChainReadBudgetExceeded;
+/**
+ * The counting wrapper built per request around the chain reader. Every method delegates to the
+ * wrapped reader but spends one unit of budget first; the call that would exceed it throws instead
+ * of running, so the platform's own subrequest ceiling is never reached. It extends RegistryReader
+ * on purpose: the class has an ECMAScript private field, which makes it nominal in TypeScript — a
+ * structural stand-in could never be passed where a RegistryReader is expected. Route code reads
+ * `remaining` to size its own scan caps (pending re-checks, object lists) so this wrapper's throw
+ * stays the last line of defence, not the control flow.
+ */
+export declare class BudgetedReader extends RegistryReader {
+    #private;
+    /**
+     * `memo` is the operation-scope the request belongs to (in-9 R-5): when the caller carries a
+     * read-scope token, the app hands every request of that operation the same map, so an identical
+     * NON-AUTHORIZATION question a sibling request already asked is answered once per operation.
+     * in-12 N-10 draws the line: an authorization answer — identity resolution, the agent record,
+     * capability and epoch state, the authority verdict — is never shared across HTTP requests, so a
+     * token held past a revocation can only ever return content verifications, never a stale
+     * "allowed". A memo hit spends no budget: it is not a chain read at all. A rejected call is
+     * evicted so one transient failure never poisons the operation.
+     */
+    constructor(inner: RegistryReader, limit?: number, memo?: Map<string, Promise<unknown>>);
+    /** Chain reads spent so far in this request. */
+    get spent(): number;
+    /** Reads still available; route logic sizes its own caps from this before asking the chain. */
+    get remaining(): number;
+    now(): Promise<bigint>;
+    agentIdOfSigner(signer: Address): Promise<Hex | null>;
+    getAgent(agentId: Hex): Promise<AgentRecord | null>;
+    getCapability(capabilityId: Hex): Promise<CapabilityView | null>;
+    agentEpoch(owner: Address, agentId: Hex): Promise<bigint>;
+    activeCapabilityIds(owner: Address, agentId: Hex): Promise<readonly Hex[]>;
+    hasAuthority(owner: Address, agentId: Hex, namespaceId: Hex, permissions: number, provenanceBits: number): Promise<boolean>;
+    requiredReadEpoch(owner: Address, namespaceId: Hex): Promise<bigint>;
+    epochPublicKey(owner: Address, namespaceId: Hex, epoch: bigint): Promise<Hex | null>;
+    isWriteEpochValid(owner: Address, namespaceId: Hex, epoch: bigint): Promise<boolean>;
+    ownerP256Key(owner: Address): Promise<{
+        qx: bigint;
+        qy: bigint;
+    } | null>;
+    getRecord(contextId: Hex): Promise<ContextRecordView | null>;
+    recordBatchSize(): Promise<number>;
+    getRecords(contextIds: readonly Hex[]): Promise<(ContextRecordView | null)[]>;
+}

package/dist/types/api/chain-views.d.ts

@@ -0,0 +1,87 @@
+import type { Address, AgentRecord, Hex } from "../protocol/index.js";
+import type { ChainContext } from "../chain/index.js";
+/** Spec §10.3 Capability, as read from CapabilityRegistry. */
+export interface CapabilityView {
+    owner: Address;
+    agentId: Hex;
+    namespaceId: Hex;
+    permissions: number;
+    provenancePolicy: number;
+    issuedAt: bigint;
+    expiresAt: bigint;
+    agentEpoch: bigint;
+    grantedAtReadEpoch: bigint;
+    revoked: boolean;
+}
+/** Spec §11.3 ContextRecord, as read from ContextRegistry. */
+export interface ContextRecordView {
+    contextId: Hex;
+    owner: Address;
+    author: Hex;
+    namespaceId: Hex;
+    lineageId: Hex;
+    parentId: Hex;
+    manifestHash: Hex;
+    ciphertextCommitment: Hex;
+    evidenceCommitment: Hex;
+    readEpoch: bigint;
+    createdAt: bigint;
+    expiresAt: bigint;
+    version: number;
+    recordType: number;
+    lineagePolicy: number;
+    kind: number;
+    provenanceSource: number;
+}
+/** The most contextIds one batched `getRecords` asks about — one Multicall3 `eth_call` per batch. */
+export declare const RECORDS_PER_MULTICALL = 200;
+/**
+ * Every Monad read the Context API and SDK make. Nothing here is cached: each call reads current chain state, so no
+ * local value can make Monad authorization true (§12, `currentlyAllowedByMonad`).
+ */
+export declare class RegistryReader {
+    #private;
+    readonly context: ChainContext;
+    constructor(context: ChainContext);
+    /**
+     * The probed batch size once known, undefined while unprobed. Lets a BudgetedReader return a
+     * cached answer without charging the request for a chain read that does not happen.
+     */
+    get knownRecordBatchSize(): number | undefined;
+    /**
+     * The most contextIds one `getRecords` call answers in a single chain read: RECORDS_PER_MULTICALL
+     * when the chain carries Multicall3, 1 where it does not. Probed once per reader with `getCode`
+     * and cached; a chain that cannot answer the probe cannot run a multicall either, so a failed
+     * probe also resolves to 1 — the per-row path — rather than breaking reads on an RPC that does
+     * not serve `eth_getCode`.
+     */
+    recordBatchSize(): Promise<number>;
+    now(): Promise<bigint>;
+    agentIdOfSigner(signer: Address): Promise<Hex | null>;
+    getAgent(agentId: Hex): Promise<AgentRecord | null>;
+    getCapability(capabilityId: Hex): Promise<CapabilityView | null>;
+    agentEpoch(owner: Address, agentId: Hex): Promise<bigint>;
+    /** Capability IDs ever granted by this owner to this agent; revoked/expired entries linger until a grant compacts the list. */
+    activeCapabilityIds(owner: Address, agentId: Hex): Promise<readonly Hex[]>;
+    hasAuthority(owner: Address, agentId: Hex, namespaceId: Hex, permissions: number, provenanceBits: number): Promise<boolean>;
+    requiredReadEpoch(owner: Address, namespaceId: Hex): Promise<bigint>;
+    epochPublicKey(owner: Address, namespaceId: Hex, epoch: bigint): Promise<Hex | null>;
+    isWriteEpochValid(owner: Address, namespaceId: Hex, epoch: bigint): Promise<boolean>;
+    ownerP256Key(owner: Address): Promise<{
+        qx: bigint;
+        qy: bigint;
+    } | null>;
+    getRecord(contextId: Hex): Promise<ContextRecordView | null>;
+    /**
+     * `getRecord` for a batch of contextIds. With Multicall3 the batch is ONE `eth_call` — hundreds of
+     * never-anchored uploads can no longer spend a request's read budget a row at a time. The
+     * `ContextNotFound` revert of an orphaned upload comes back as a null entry — "not anchored",
+     * never an error — and it is the ONLY failure that does: an out-of-gas, an undecodable result or
+     * any other revert throws exactly as `getRecord` throws, so a caller can never read a list that
+     * silently dropped a real record. Chains without Multicall3 fall back to one `getRecord` per id,
+     * unchanged.
+     * Callers pass at most `recordBatchSize()` ids per call, so each call costs exactly one unit of
+     * read budget — or `contextIds.length` units on the per-row path, identical to `getRecord`.
+     */
+    getRecords(contextIds: readonly Hex[]): Promise<(ContextRecordView | null)[]>;
+}

package/dist/types/api/client.d.ts

@@ -0,0 +1,295 @@
+import type { Address, BatchSaveMessage, Hex, ObjectManifest, ReaderEpochWrap, SignedAgentCapabilityManifest } from "../protocol/index.js";
+import type { LocalAccount } from "viem";
+import type { WebAuthnAssertionInput } from "./verify-assertion.js";
+import type { AnchoredObject, ObjectUploadBody } from "./wire.js";
+import type { DenyState, RevocationTarget } from "./deny-overlay.js";
+export interface ContextApiClientOptions {
+    baseUrl: string;
+    account: LocalAccount;
+    chainId: bigint;
+    capabilityRegistry: Address;
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+    clock?: () => bigint;
+    /**
+     * The one logical read operation this client's requests belong to (in-9 R-5, hardened in-12
+     * N-10): signer address → the read-scope token the server issued it. The token is minted by the
+     * server — HMAC-signed, signer-bound, eight seconds — so this map is only ever filled from
+     * response headers: a request stamps the token it currently holds, then adopts the fresh one the
+     * response carries once the held one has lapsed. Never set on a client that outlives one
+     * operation.
+     */
+    readScope?: Map<string, string>;
+    /**
+     * Where the store's compat warnings land (in-12 N-7): default stderr — right for a bare
+     * script — while the daemon passes its own log so the line reaches a log someone reads.
+     * Once per process either way.
+     */
+    warn?: (message: string) => void;
+}
+/**
+ * Signs every request with MidaHttpRequestV1 (§12.1); the signature covers the exact body bytes sent. The typed route
+ * methods implement the FakeVault's VaultContextApi port structurally, so the same client serves owners and agents.
+ */
+export declare class ContextApiClient implements ContextApiRoutes {
+    #private;
+    readonly account: LocalAccount;
+    constructor(options: ContextApiClientOptions);
+    request<T>(method: string, path: string, options?: {
+        query?: Record<string, string>;
+        body?: unknown;
+        signed?: boolean;
+    }): Promise<T>;
+    putObject(upload: ObjectUploadBody): Promise<{
+        contextId: Hex;
+        manifestHash: Hex;
+        state: "pending";
+    }>;
+    /**
+     * The pre-register question (in-3 I6): may this signer register for `owner`/`namespaceId` with
+     * this capability right now? Answers 200 or throws the store's code — WRITE_DENIED while the
+     * owner's revoke is only staged (pending on Monad), CAPABILITY_REVOKED once it has landed.
+     */
+    writeAuthority(input: {
+        owner: Address;
+        namespaceId: Hex;
+        capabilityId: Hex;
+        expectedParentId?: Hex;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: true;
+    }>;
+    listObjects(input: {
+        owner: Address;
+        namespaceId: Hex;
+        capabilityId?: Hex;
+    }): Promise<ListObjectsResult>;
+    getManifest(contextId: Hex, capabilityId?: Hex): Promise<{
+        manifest: ObjectManifest;
+        manifestHash: Hex;
+    }>;
+    putAgentManifest(envelope: SignedAgentCapabilityManifest): Promise<{
+        bodyHash: Hex;
+        envelopeHash: Hex;
+    }>;
+    getAgentManifest(bodyHash: Hex): Promise<SignedAgentCapabilityManifest>;
+    publishEpochWrap(wrap: ReaderEpochWrap): Promise<{
+        stored: true;
+    }>;
+    getEpochWrap(input: {
+        owner: Address;
+        namespaceId: Hex;
+        readEpoch: bigint;
+        agentId: Hex;
+        agentKeyVersion: number;
+        capabilityId: Hex;
+    }): Promise<ReaderEpochWrap>;
+    requestRevocationDeny(target: {
+        capabilityId: Hex;
+    } | {
+        owner: Address;
+        agentId: Hex;
+    }): Promise<{
+        intentId: Hex;
+        state: string;
+        cancellationNonce: string;
+    }>;
+    cancelRevocation(intentId: Hex, input: {
+        expiresAt: bigint;
+        assertion: WebAuthnAssertionInput;
+    }): Promise<{
+        intentId: Hex;
+        state: string;
+    }>;
+    listRevocations(state?: DenyState): Promise<RevocationIntentView[]>;
+    reissueRevocationNonce(intentId: Hex): Promise<{
+        intentId: Hex;
+        state: string;
+        cancellationNonce: string;
+    }>;
+    batchStatus(): Promise<{
+        enabled: boolean;
+        batchAnchor?: Address;
+        reason?: string;
+        message?: string;
+    }>;
+    postBatchSave(body: BatchedSaveWire): Promise<{
+        state: "QUEUED";
+        receipt: BatchReceipt;
+    }>;
+    getBatchSave(contextId: Hex, capabilityId?: Hex): Promise<{
+        state: BatchedItemState | "REJECTED";
+        reason: string | null;
+        item?: BatchedReadItem;
+    }>;
+    listBatchSaves(input: {
+        owner: Address;
+        namespaceId: Hex;
+        capabilityId?: Hex;
+    }): Promise<{
+        items: BatchedReadItem[];
+        partial: boolean;
+    }>;
+    flushBatch(): Promise<{
+        flushed: boolean;
+        reason?: "empty" | "rate-limited";
+    }>;
+}
+/**
+ * The store answered HTTP `status` with bytes that are not a Mida body — an old deploy's
+ * plain-text 404 on a route it does not have, a proxy or Cloudflare error page (in-11 R-3).
+ * Carries the status so a caller can route on it; the drain reads `code` for a stable name.
+ * This replaced the bare `SyntaxError` a JSON.parse used to leave, which the drain could only
+ * file as an anonymous "chain-error" and retry eight times before dropping the save.
+ */
+export declare class StoreHttpError extends Error {
+    readonly status: number;
+    readonly code = "STORE_UNREACHABLE";
+    constructor(status: number, body: string);
+}
+/** Retries `listObjects` performs after the first response still carries `x-mida-partial`. */
+export declare const LIST_PARTIAL_MAX_RETRIES = 3;
+/**
+ * What `listObjects` returns: the objects it verified plus `partial` — true when the server left
+ * rows unexamined after the initial request and all retries. An honest field, never a hidden
+ * property: a caller that ignores it cannot mistake a truncated list for a complete one.
+ */
+export interface ListObjectsResult {
+    objects: AnchoredObject[];
+    partial: boolean;
+}
+/**
+ * What `GET /revocations` returns per intent: everything an owner needs to find and cancel a stale
+ * deny — except the cancellation nonce, which the store only hands out when the deny is created or
+ * its nonce reissued.
+ */
+export interface RevocationIntentView {
+    intentId: Hex;
+    state: DenyState;
+    target: RevocationTarget;
+    agentEpochAtIntent: string | null;
+}
+/** Wire form of `BatchSaveMessage`: the two uint64 fields travel as base-10 strings, everything else verbatim. */
+export type BatchedSaveMessageWire = Omit<BatchSaveMessage, "readEpoch" | "expiresAt"> & {
+    readEpoch: string;
+    expiresAt: string;
+};
+export interface BatchedSaveWire {
+    message: BatchedSaveMessageWire;
+    signature: Hex;
+    manifest: ObjectManifest;
+    ciphertext: Hex;
+}
+/**
+ * "HELD" is the in-3 store-side hold: the row's author is on the active deny list, so the batcher
+ * keeps it off the send path while the revoke is pending on Monad — it re-joins QUEUED when the
+ * deny clears with the grant still valid, or becomes REJECTED once the revoke lands.
+ */
+export type BatchedItemState = "QUEUED" | "SUBMITTED" | "ANCHORED" | "HELD";
+export interface BatchedReadItem {
+    state: BatchedItemState;
+    save: BatchedSaveWire;
+    contextId: Hex;
+    receivedAt: number;
+    batchId?: Hex;
+    position?: number;
+    lineageId?: Hex;
+    version?: number;
+    proof?: Hex[];
+}
+export interface BatchReceipt {
+    contextId: Hex;
+    receivedAt: number;
+    sequence: string;
+    signature: Hex;
+}
+export interface ContextApiRoutes {
+    putObject(upload: ObjectUploadBody): Promise<{
+        contextId: Hex;
+        manifestHash: Hex;
+        state: "pending";
+    }>;
+    writeAuthority(input: {
+        owner: Address;
+        namespaceId: Hex;
+        capabilityId: Hex;
+        expectedParentId?: Hex;
+    }): Promise<{
+        ok: true;
+    }>;
+    listObjects(input: {
+        owner: Address;
+        namespaceId: Hex;
+        capabilityId?: Hex;
+    }): Promise<ListObjectsResult>;
+    getManifest(contextId: Hex, capabilityId?: Hex): Promise<{
+        manifest: ObjectManifest;
+        manifestHash: Hex;
+    }>;
+    putAgentManifest(envelope: SignedAgentCapabilityManifest): Promise<{
+        bodyHash: Hex;
+        envelopeHash: Hex;
+    }>;
+    getAgentManifest(bodyHash: Hex): Promise<SignedAgentCapabilityManifest>;
+    publishEpochWrap(wrap: ReaderEpochWrap): Promise<{
+        stored: true;
+    }>;
+    getEpochWrap(input: {
+        owner: Address;
+        namespaceId: Hex;
+        readEpoch: bigint;
+        agentId: Hex;
+        agentKeyVersion: number;
+        capabilityId: Hex;
+    }): Promise<ReaderEpochWrap>;
+    requestRevocationDeny(target: {
+        capabilityId: Hex;
+    } | {
+        owner: Address;
+        agentId: Hex;
+    }): Promise<{
+        intentId: Hex;
+        state: string;
+        cancellationNonce: string;
+    }>;
+    cancelRevocation(intentId: Hex, input: {
+        expiresAt: bigint;
+        assertion: WebAuthnAssertionInput;
+    }): Promise<{
+        intentId: Hex;
+        state: string;
+    }>;
+    listRevocations(state?: DenyState): Promise<RevocationIntentView[]>;
+    reissueRevocationNonce(intentId: Hex): Promise<{
+        intentId: Hex;
+        state: string;
+        cancellationNonce: string;
+    }>;
+    batchStatus(): Promise<{
+        enabled: boolean;
+        batchAnchor?: Address;
+        reason?: string;
+        message?: string;
+    }>;
+    postBatchSave(body: BatchedSaveWire): Promise<{
+        state: "QUEUED";
+        receipt: BatchReceipt;
+    }>;
+    getBatchSave(contextId: Hex, capabilityId?: Hex): Promise<{
+        state: BatchedItemState | "REJECTED";
+        reason: string | null;
+        item?: BatchedReadItem;
+    }>;
+    listBatchSaves(input: {
+        owner: Address;
+        namespaceId: Hex;
+        capabilityId?: Hex;
+    }): Promise<{
+        items: BatchedReadItem[];
+        partial: boolean;
+    }>;
+    flushBatch(): Promise<{
+        flushed: boolean;
+        reason?: "empty" | "rate-limited";
+    }>;
+}

package/dist/types/api/deny-overlay.d.ts

@@ -0,0 +1,81 @@
+import type { Address, Hex } from "../protocol/index.js";
+import type { RegistryReader } from "./chain-views.js";
+import type { DenyStore } from "./stores.js";
+export type RevocationTarget = {
+    kind: "capability";
+    capabilityId: Hex;
+} | {
+    kind: "agent";
+    agentId: Hex;
+};
+export type DenyState = "active" | "anchored" | "cancelled";
+export interface RevocationIntent {
+    id: Hex;
+    owner: Address;
+    target: RevocationTarget;
+    state: DenyState;
+    /** Owner-agent epoch when the intent was recorded; an agent revocation is anchored once the chain epoch exceeds it. */
+    agentEpochAtIntent: string | null;
+    /** Base-10 uint256 consumed by a successful cancellation; null once consumed or no longer cancellable. */
+    cancellationNonce: string | null;
+}
+/** The persisted shape `denies`, `reconcile` and `cancel` dereference; a malformed entry fails construction. */
+export declare function isRevocationIntent(value: unknown): value is RevocationIntent;
+/**
+ * The file-backed DenyStore: the revocation intents as one JSON file, kept in memory once loaded and rewritten
+ * atomically on every mutation. An unreadable or malformed file fails closed at construction: starting empty would
+ * silently restore authority a pending deny removed, which §12.5 forbids. Only a missing file means a fresh start.
+ */
+export declare class FileDenyStore implements DenyStore {
+    #private;
+    constructor(file: string);
+    list(): Promise<RevocationIntent[]>;
+    get(id: Hex): Promise<RevocationIntent | undefined>;
+    insert(intent: RevocationIntent): Promise<void>;
+    update(intent: RevocationIntent): Promise<void>;
+}
+/**
+ * §12.5 fast revocation overlay over a DenyStore. Exactly three transitions exist:
+ *   active → anchored   matching Monad revocation observed (reconcile)
+ *   active → active     transaction failed, missing or reorged out (no timeout ever clears a deny)
+ *   active → cancelled  fresh owner P256-approved cancellation (cancel)
+ * It can only reduce authority: `effectiveAllowed = currentlyAllowedByMonad AND NOT localDeny`.
+ */
+export declare class DenyOverlay {
+    #private;
+    constructor(store: DenyStore | string);
+    list(): Promise<RevocationIntent[]>;
+    get(id: Hex): Promise<RevocationIntent | undefined>;
+    create(owner: Address, target: RevocationTarget, agentEpochAtIntent: bigint | null): Promise<RevocationIntent>;
+    /** True when an active deny matches this owner and either this agent relationship or this exact capability. */
+    denies(input: {
+        owner: Address;
+        agentId: Hex;
+        capabilityId: Hex;
+    }): Promise<boolean>;
+    /**
+     * For wrap publication, which names no capability: an active deny on this agent, or on any of its capabilities in
+     * this namespace, blocks publication.
+     */
+    deniesRelationship(reader: RegistryReader, input: {
+        owner: Address;
+        agentId: Hex;
+        namespaceId: Hex;
+    }): Promise<boolean>;
+    /** active → anchored only when Monad shows the matching revocation. Failed or missing transactions leave it active. */
+    reconcile(reader: RegistryReader): Promise<void>;
+    /**
+     * The same pass narrowed to one owner (M3-D6): a request authenticated as an owner must not
+     * spend chain reads on every other owner's intents — reconcile only what the caller may see.
+     */
+    reconcileOwner(reader: RegistryReader, owner: Address): Promise<void>;
+    /**
+     * Re-arms an active intent with a fresh cancellation nonce and retires the old ticket (M3-D4).
+     * The creation response is the only other place a nonce leaves the store; an owner clearing a
+     * stale deny it did not just stage — a revoke that failed on an earlier run — needs a new one.
+     * Anything but active refuses: an anchored intent must never be re-armed.
+     */
+    reissueNonce(id: Hex, owner: Address): Promise<RevocationIntent>;
+    /** active → cancelled. The caller must already have verified a fresh P256 assertion over this nonce. */
+    cancel(id: Hex, owner: Address, nonce: bigint): Promise<RevocationIntent>;
+}

package/dist/types/api/errors.d.ts

@@ -0,0 +1,30 @@
+import type { MidaErrorCode } from "../protocol/index.js";
+export interface ApiErrorBody {
+    error: {
+        code: MidaErrorCode;
+        message: string;
+    };
+}
+export declare function statusFor(code: MidaErrorCode): number;
+/**
+ * Unknown failures never leak internals and never read as authorization (in-6 R4). The chain
+ * error's kind picks the answer (in-11 R-8): a genuinely unreachable RPC — rate-limited, 5xx,
+ * dropped, timed out, or this request's own Monad read budget — is 503 CHAIN_UNAVAILABLE and
+ * retryable; an RPC that answered "no contract here" is 502 CHAIN_MISCONFIGURED and a provider
+ * that refused the key is 502 RPC_AUTH_REJECTED, neither retryable. A viem failure that is none
+ * of those — the chain answered something unexpected — is 500 INTERNAL_ERROR rather than a 503
+ * that would lie "unreachable". All still return no data (fail closed): the Sep 25 incident was
+ * a busy RPC wearing CAPABILITY_DENIED.
+ *
+ * `options.rpcHint` names THIS store's RPC-endpoint setting in the operator hint (in-14 F-4):
+ * the hosted Worker's is the RPC_URL variable; the local persistent store's is the rpcUrl key in
+ * network.json. A caller that passes neither gets a setting-neutral hint rather than a name that
+ * store does not have.
+ */
+export declare function toErrorBody(error: unknown, options?: {
+    rpcHint?: string;
+}): {
+    status: number;
+    body: ApiErrorBody;
+};
+export declare function errorFromBody(status: number, body: unknown): Error;

package/dist/types/api/file-stores.d.ts

@@ -0,0 +1,7 @@
+import type { ContextStores } from "./stores.js";
+/**
+ * The default stores: one directory on the local filesystem holding the object metadata, content-addressed blobs,
+ * replay log and deny overlay. `createContextApi` builds these when it is given `dataDir` and no `stores`, so the
+ * local `midad` server and every existing test run exactly the app they ran before.
+ */
+export declare function fileStores(dataDir: string): ContextStores;

package/dist/types/api/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./auth.js";
+export * from "./authorize.js";
+export * from "./batch-deny.js";
+export * from "./batch-routes.js";
+export * from "./batch-store.js";
+export * from "./batcher.js";
+export * from "./chain-budget.js";
+export * from "./chain-views.js";
+export * from "./client.js";
+export * from "./deny-overlay.js";
+export * from "./errors.js";
+export * from "./file-stores.js";
+export * from "./stores.js";
+export * from "./verify-assertion.js";
+export * from "./app.js";
+export * from "./store.js";
+export * from "./wire.js";

package/dist/types/api/secure-fs.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The data tree holds ciphertext, reader wraps and auth state — it is user-only: every directory
+ * is mode 0700 and every file 0600, the same rules the midad home follows. `secureDir` makes a
+ * folder (and every ancestor down to `root`) exist at 0700, `writeJsonAtomic` is the home's
+ * writeSecretJson shape (temp file opened "wx" 0600, fsynced, renamed over the target, parent
+ * fsynced), and `repairModes` re-pins an existing tree at startup so a folder made before these
+ * rules — or chmodded by hand — is corrected rather than trusted.
+ */
+export declare function secureDir(root: string, dir: string): void;
+export declare function writeJsonAtomic(root: string, path: string, value: unknown): void;
+/** Creates `root` at 0700 if absent, then walks the whole tree pinning dirs to 0700 and files to 0600. */
+export declare function repairModes(root: string): void;

package/dist/types/api/store.d.ts

@@ -0,0 +1,51 @@
+import type { Address, Hex, ObjectManifest, ReaderEpochWrap } from "../protocol/index.js";
+import { FsStorage } from "../storage/index.js";
+import type { ManifestIndexEntry, ObjectStore, WrapKey } from "./stores.js";
+/** A ciphertext upload's immutable metadata. Served as context only after Monad holds matching commitments (§12.2). */
+export interface StoredObject {
+    contextId: Hex;
+    owner: Address;
+    /** The authenticated signer that uploaded it; feeds the per-signer quotas. Absent in pre-M3 files → read as owner. */
+    uploader: Address;
+    namespaceId: Hex;
+    authorId: Hex;
+    objectNonce: Hex;
+    expectedParentId: Hex;
+    manifest: ObjectManifest;
+    manifestHash: Hex;
+    uploadedAt: string;
+    /**
+     * ISO-8601 UTC of the first verified isAnchored match, or null while pending. Set once, never cleared:
+     * a Monad record cannot be un-registered, so a row that matched once matches forever. Absent in
+     * pre-M3-A2 files → read as null (pending), which is always safe — it only costs a re-check.
+     */
+    anchoredAt: string | null;
+}
+/**
+ * The file-backed ObjectStore, the default when `createContextApi` is given a data directory: content-addressed
+ * blobs in FsStorage (ciphertext and signed manifest envelopes), plus JSON files for object metadata, reader wraps,
+ * the manifest body-hash index and the per-signer PUT counts. Every path segment is validated hex. Being a
+ * single-writer file store, its check-and-record operations are trivially atomic.
+ */
+export declare class ApiStore implements ObjectStore {
+    #private;
+    readonly blobs: FsStorage;
+    constructor(dataDir: string);
+    putObject(object: StoredObject): Promise<void>;
+    getObject(contextId: Hex): Promise<StoredObject | undefined>;
+    listObjects(owner: Address, namespaceId: Hex): Promise<StoredObject[]>;
+    putObjectWithinPending(object: StoredObject, maxPendingBytes: number, blob: Uint8Array, pendingSince?: Date): Promise<"stored" | "repeat" | "over-cap">;
+    pendingByUploader(uploader: Address): Promise<StoredObject[]>;
+    markAnchored(contextId: Hex, anchoredAt: string): Promise<void>;
+    putWrap(wrap: ReaderEpochWrap): Promise<void>;
+    getWrap(key: WrapKey): Promise<ReaderEpochWrap | undefined>;
+    setManifestIndex(bodyHash: Hex, envelopeHash: Hex, opts?: {
+        storedAt?: string;
+        verifiedAt?: string | null;
+    }): Promise<void>;
+    getManifestIndex(bodyHash: Hex): Promise<ManifestIndexEntry | undefined>;
+    recordPut(signer: Address, day: string): Promise<number>;
+    recordManifestPut(signer: Address, day: string): Promise<number>;
+    sweepPending(olderThan: Date, stillPending: (object: StoredObject) => Promise<boolean>, blobGraceCutoff?: Date): Promise<number>;
+    sweepManifests(olderThan: Date, blobGraceCutoff?: Date): Promise<number>;
+}