@osyra/ome

Pre-release — offline verification only: Offline verification from an authorized source checkout is usable. The memory/network RPC surface and any api.osyra.ai examples below describe protocol/interface shape only. The public Edge bridge, package publication, and release acceptance are still pending; do not treat this page as proof that customer network read/write is available.

Import: import { … } from "@osyra/ome";

Re-exports

Symbols re-exported from another entry point. Follow the link for the full definition.

| Symbol | Defined in | | --- | --- | | OME_MCP_CLIENT_CONTRACT_VERSION | OME_MCP_CLIENT_CONTRACT_VERSION | | OmeMcpBundleManifest | OmeMcpBundleManifest | | OmeMcpCallContext | OmeMcpCallContext | | OmeMcpClaimBody | OmeMcpClaimBody | | OmeMcpClaimKind | OmeMcpClaimKind | | OmeMcpClientContractVersion | OmeMcpClientContractVersion | | OmeMcpClientV1 | OmeMcpClientV1 | | OmeMcpListFilter | OmeMcpListFilter | | OmeMcpListResult | OmeMcpListResult | | OmeSignerKeySource | OmeSignerKeySource | | OmeSignerOptions | OmeSignerOptions |

Classes

InferenceClient

class InferenceClient

A producer client for the edge inference SSE stream + its OIR receipt.

Construct with the edge inference stream URL (…/api/v1/inference/stream) + the same bearer JWT the gRPC OmeClient uses. Pass options.fetch to inject a custom (or mock) transport.

constructor(inferenceUrl: string, options?: InferenceClientOptions): InferenceClient

Methods

complete(model: string, args?: InferenceArgs): Promise<InferenceResult>

Drive an inference to completion and return the assembled output + the OIR receipt. Consumes the whole SSE stream. Throws OmeAuthError / OmePolicyError / OmeRateLimitError / OmeServerError / OmeTransportError / OmeWireFormatError on auth / policy / rate-limit / transport / malformed failures; a normal stream returns an InferenceResult (with oirB64 === undefined when the gateway did not emit a receipt — never a fabricated one).

stream(model: string, args?: InferenceArgs): AsyncGenerator<string>

Yield each delta token as it arrives (the terminal OIR frame carries no delta).

OmeAuthError

class OmeAuthError extends OmeError

Authentication failure: bad token, expired token, wrong workspace. OSY-AUTH-1101 per design doc §3.5.

constructor(message: string, options?: { cause?: unknown }): OmeAuthError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeBundleError

class OmeBundleError extends OmeError

Bundle manifest invalid, ZIP entry mismatch, root hash mismatch. OSY-VALID-4530 per design doc §3.5.

constructor(message: string, options?: { cause?: unknown }): OmeBundleError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeClient

class OmeClient implements OmeMcpClientV1

OmeClient — namespaced top-level client.

Construction is synchronous and cheap (no I/O); transport binding happens lazily on first RPC call. Lifecycle via await using or explicit await client.close().

constructor(options: OmeClientOptions): OmeClient

Properties

| Name | Type | Description | | --- | --- | --- | | readonly mcpContractVersion | "1.0.0" | Runtime drift gate consumed by AP00015. | | readonly memory | MemoryNamespace | memory namespace — read+write (NDA-restricted in non-verify subpath) | | readonly options | Required<Pick<OmeClientOptions, "auth" \| "workspace">> & OmeClientOptions | Captured options (DEEP-FROZEN + read-only after construction). F032: options.auth carries REDACTED secret fields — the raw token / refreshToken / signingKey live ONLY in the private #secrets store, never on this public surface. The whole object graph is Object.freezed (deeply), so it cannot be mutated at runtime (the TS readonly is compile-time only). | | readonly proof | ProofNamespace | proof namespace — JMT prove + verify | | readonly verify | VerifyNamespace | verify namespace — read-only (Apache-2.0) | | readonly witness | WitnessNamespace | witness namespace — completeness witness build + verify | | closed (get) | boolean | True iff close() has been called |

Methods

[asyncDispose](): Promise<void>

Symbol.asyncDispose support for await using client = new OmeClient(...). TC39 Stage 3 explicit resource management.

checkPolicy(action: string, resource?: string, context?: Record<string, string>, ctx?: OmeMcpCallContext): Promise<CheckPolicyResult>

ENG-2569 (ARC-36 / MCP-C-32/38 / ADR-291): the osymem.policy.check pre-flight — ask the OME backend for the would-be admission verdict for action (optionally on resource, with bounded non-PII context) WITHOUT performing the action.

IMPLEMENTED RPC path (ENG-2585; public Edge route pending), FAIL-CLOSED IMPLICIT_DENY (ADR-291 D3): the call invokes OME's CheckPolicy query RPC and returns the server verdict (which may itself be IMPLICIT_DENY, carrying a replayable policyVersion + server-minted decisionId). On a TRANSPORT-class failure (unreachable enforcer / timeout) the SDK fail-closes to a CheckPolicyResult with decision = "IMPLICIT_DENY" and EMPTY policyVersion/decisionId — a deny is a RESULT, a transport error NEVER reads as ALLOW, and the empty replay fields let a caller distinguish the fail-closed sentinel from a real server verdict. A non-transport error (e.g. a bad-argument / permission denial) propagates as a typed Ome*Error.

Throws: OmeWireFormatError on a client-side validation failure (empty/oversized action, oversized resource).

close(): Promise<void>

Graceful shutdown. Releases the Connect-RPC transport and marks the client closed; every subsequent namespaced call rejects with OmeClosedClientError.

The Node Connect transport's underlying HTTP/2 sessions are owned by the Http2SessionManager inside the transport and are reclaimed when the client is dropped + the process drains; there is no explicit destroy on the Connect-ES v2 client surface, so close() drops our reference (so a closed client cannot issue new RPCs) and resolves. shutdownGraceMs is reserved for an explicit-drain implementation if the transport surface adds one.

getServerSpec(ctx?: OmeMcpCallContext): Promise<ServerSpec>

ENG-2568 (ARC-36 / MCP-C-37 / ADR-292): fetch the OME backend's advertised spec identity (ServerSpec: specId + optional specVersion + region).

Intended use is a STARTUP fail-closed binding: a client (notably the AP00015 MCP server) pins an expected osyra.spec_id and ABORTS startup if getServerSpec().specId disagrees — never serving against a spec-divergent backend (ADR-292 §5.4 step 5).

IMPLEMENTED RPC path (ENG-2585; public Edge route pending). Calls OME's GetServerSpec RPC. A transport failure surfaces as a typed Ome*Error — the SDK NEVER fabricates a spec. ADR-292 D3 prescribes the CALLER treat that rejection as a CARRIED fallback (validate against local config + WARN), never a silent ALLOW.

Throws: Ome*Error on a transport / server failure (never a fabricated spec).

toJSON(): { options: Required<Pick<OmeClientOptions, "auth" | "workspace">> & OmeClientOptions }

Serialization view (F032 hardening). JSON.stringify(client) — directly or nested (JSON.stringify({ wrapped: client })) — invokes this method and emits ONLY the already-redacted public options (whose auth carries the "[redacted]" sentinels), NEVER the raw secret store. The #secrets field is a #private field so it is already non-enumerable and unreachable by a generic serializer; toJSON() is the belt-and-suspenders guarantee that the SHAPE serialized is the curated public view rather than the whole instance (which also carries the namespace closures). Returns a plain object — the frozen options is structurally cloned by JSON.stringify regardless.

OmeClosedClientError

class OmeClosedClientError extends OmeError

Operation attempted after client.close().

Lifecycle invariant: once a client has been closed (explicitly or via Symbol.asyncDispose), every namespaced method must reject promptly with this typed error — not a generic Error. Customers may pattern match on kind === "client_closed" to retry against a fresh client.

Code: OSY-SERVER-9007 (F098/F037 fix — .code MUST be a discriminator). Previously shared OSY-SERVER-9001 with OmeServerError (INTERNAL_ERROR) and OmeNotImplementedError, so a closed-client lifecycle rejection was indistinguishable from a server-internal error on .code alone. 9007 is a client-side lifecycle condition (operation after close()), distinct from the canonical 9001 INTERNAL_ERROR / 9002 SERVICE_UNAVAILABLE / 9050 NOT_IMPLEMENTED. OSY-SERVER-9007 is NOT yet recorded in the canonical osyra-response-common ErrorCodes registry — flagged for spec allocation (see ENG-2414 REPORT); it is the next free code in the SERVER 9000-9099 band (9003-9006 are taken by AP00001-edge transport conditions; 9050 = NOT_IMPLEMENTED). Per design doc §4.3 (HIGH-ARCH-CRIT-4 fold-in).

constructor(message: string, options?: { cause?: unknown }): OmeClosedClientError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeError

class OmeError extends Error

Root error class shared by the verify subpath and the full SDK.

Customer code may rely on: try { ... } catch (e) { if (e instanceof OmeError) { ...handle SDK error... } }

Both src/errors.ts (NDA full SDK) and src/verify/_errors.ts (Apache-2.0 verify subpath) export the SAME OmeError class identity. The full SDK re-exports from this file so there is exactly one OmeError prototype at runtime.

constructor(kind: string, code: string, message: string, options?: { cause?: unknown }): OmeError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeInvalidSignatureError

class OmeInvalidSignatureError extends OmeError

Ed25519 signature mismatch on a known-good preimage, or malformed signature/public-key length. Specialization of OmeVerifyError. OSY-VALID-4520.

constructor(message: string, options?: { cause?: unknown }): OmeInvalidSignatureError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeMalformedCborError

class OmeMalformedCborError extends OmeError

Malformed CBOR — couldn't decode the wire bytes at all. Specialization of OmeWireFormatError. OSY-VALID-4521.

constructor(message: string, options?: { cause?: unknown }): OmeMalformedCborError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeNotFoundError

class OmeNotFoundError extends OmeError

Resource not found (claim, workspace, bundle). OSY-VALID-4001 — re-uses workspace-error namespace per design doc §3.5 (no separate not_found code in V1 floor).

constructor(message: string, options?: { cause?: unknown }): OmeNotFoundError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeNotImplementedError

class OmeNotImplementedError extends OmeError

A design-sanctioned v0.2 surface method invoked on a v1.0.0 client.

The verify surface + the memory write/read/list/tombstone/export path are wired (Connect-RPC, ENG-2585). This error is the fail-closed throw for the surfaces that are intentionally NOT implemented yet: memory.batchWrite / exportBundle / importBundle, proof.prove, proof.verify / verify.proof (the 16-ary JMT proof KAT is the prerequisite, ENG-1227), witness.build, and verifyBundleZip.

Code: OSY-SERVER-9050 (F098/F037 fix — .code MUST be a discriminator). Previously OSY-SERVER-9001, which collided with OmeServerError (INTERNAL_ERROR) and OmeClosedClientError. 9050 is the CANONICAL not-implemented code in the shared registry osyra-response-common ErrorCodes.NOT_IMPLEMENTED — so a "this surface is not wired yet" rejection is now distinguishable from a server-internal error on .code alone.

Lives in the verify subpath because the verify subpath also surfaces NotImpl errors for v0.2 functionality (e.g., DID resolver).

constructor(method: string, options?: { cause?: unknown }): OmeNotImplementedError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmePolicyError

class OmePolicyError extends OmeError

Policy capability scope mismatch (per ADR-040 §13). OSY-MEM-5118 per design doc §3.5.

constructor(message: string, options?: { cause?: unknown }): OmePolicyError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeQuotaError

class OmeQuotaError extends OmeError

Quota exceeded (per-workspace or per-tier limit). Specialization of OmeRateLimitError-class for billing-tier hard limits.

Code: OSY-RATE-2010 (F098/F037 fix — .code MUST be a discriminator). Previously shared OSY-RATE-2001 with OmeRateLimitError, which made a quota rejection indistinguishable from a generic rate-limit rejection on .code alone. OSY-RATE-2010 is the CANONICAL quota code in the shared registry osyra-response-common ErrorCodes.QUOTA_EXCEEDED ("Quota exceeded: {0}") — distinct from OSY-RATE-2001 ("Rate limit exceeded for scope: {0}"). Per design doc §3.5 (which originally listed only the generic OSY-RATE-2001; the 2010 allocation aligns the SDK to the canonical taxonomy — see REPORT note for the design-doc table follow-up).

constructor(message: string, options?: { cause?: unknown }): OmeQuotaError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeRateLimitError

class OmeRateLimitError extends OmeError

Rate limit exceeded (server returned RESOURCE_EXHAUSTED). OSY-RATE-2001 per design doc §3.5.

constructor(message: string, options?: { cause?: unknown; retryAfterSeconds?: number }): OmeRateLimitError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling | | readonly retryAfterSeconds? | number | Optional retry-after hint from server (seconds) |

OmeServerError

class OmeServerError extends OmeError

Server-side error (INTERNAL / UNAVAILABLE with retry guidance). OSY-SERVER-9001 per design doc §3.5.

constructor(message: string, options?: { cause?: unknown }): OmeServerError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeTransportError

class OmeTransportError extends OmeError

Transport error (gRPC UNAVAILABLE, network error, TLS handshake). OSY-SERVER-9002 per design doc §3.5.

constructor(message: string, options?: { cause?: unknown }): OmeTransportError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeUnsupportedRuntimeError

class OmeUnsupportedRuntimeError extends OmeError

Verify backend unavailable in the current runtime.

Raised by verifyEd25519 when neither Node's native crypto.verify nor Web Crypto subtle.verify is available. JS scalar-multiplication fallback is REFUSED per threat-model R-NEW-17 + PC-12 — silent degradation to non-constant-time code is never acceptable.

OSY-SERVER-9003 per design doc §3.5 + ADR-044 β extension.

constructor(message: string, options?: { cause?: unknown }): OmeUnsupportedRuntimeError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeVerifyError

class OmeVerifyError extends OmeError

Verification failure (Ed25519 verify failed, JMT proof failed, witness invalid). OSY-VALID-4520 per design doc §3.5.

constructor(message: string, options?: { cause?: unknown; code?: string }): OmeVerifyError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeWireFormatError

class OmeWireFormatError extends OmeError

Wire-format error: non-canonical CBOR shape, malformed receipt, or cross-protocol confusion (e.g., a Witness presented for verifyReceipt). OSY-VALID-4521 per design doc §3.5.

constructor(message: string, options?: { cause?: unknown; code?: string }): OmeWireFormatError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

OmeWorkspaceError

class OmeWorkspaceError extends OmeError

Workspace ID format invalid or workspace not found. OSY-VALID-4001 per design doc §3.5.

constructor(message: string, options?: { cause?: unknown }): OmeWorkspaceError

Properties

| Name | Type | Description | | --- | --- | --- | | readonly cause? | unknown | Optional underlying cause (preserves stack chain) | | readonly code | string | Stable OSY error code for programmatic handling. | | readonly kind | string | Stable discriminator for switch-case handling |

Interfaces

BundleManifest

interface BundleManifest

Portable Bundle Manifest (Phase 4 substrate).

Manifest describing a .ome archive — workspace export for offline audit, transfer, or GDPR Art-17 satisfaction.

Mirror of Python BundleManifest; mirror of Go ome.BundleManifest.

Properties

| Name | Type | Description | | --- | --- | --- | | bundleVersion | string | Bundle version (e.g., "1.0.3" per AP00011-OME-FILE-FORMAT-V1.md) | | claimCount | number | Cardinality of claims in this bundle | | createdMs | number | Unix-ms creation time (int64 wire) | | encodedCbor | Uint8Array | Bit-exact canonical-CBOR wire bytes | | jmtRoot | Uint8Array | JMT root over the bundled claims | | signature | Uint8Array | Ed25519 signature over the canonical signing payload | | signerDid | string | Bundle signer DID | | workspaceId | string | Workspace this bundle covers |

CheckPolicyResult

interface CheckPolicyResult

ENG-2569: the checkPolicy() result (mirrors CheckPolicyResponse).

Properties

| Name | Type | Description | | --- | --- | --- | | decision | PolicyDecision | The would-be admission verdict; fail-closed to IMPLICIT_DENY. | | decisionId | string | Server-minted decision correlation id (UUID). | | policyVersion | string | The enforcer's single combined cascade content-address (OpaCascadeDecider.digest() lowercase-hex; MCP-C-38) — replayable pass-through pin, NOT a per-layer array. Empty when no decider/digest was resolvable (which itself forces IMPLICIT_DENY). | | violations | string[] | Responsible cascade layer / fail-reason (diagnostic). |

Claim

interface Claim

Core claim payload (pre-signature view).

Wire-key alignment (D1 / ENG-2279 Task 4). The property names ARE the canonical Form-B claim-map SHORT KEYS — the exact 9 CTAP2-sorted text keys ws, id, sub, par, iss, ch, eh, kn, ts carried inside canonical_cbor([tstr("osyra-ome-claim-v1"), claimMap]) (per kernel.ts §"Preimage", verify/claim-fields.ts, the claim-preimage KAT, and ADR-157 Form-B). This makes the public TS surface a 1:1 mirror of the wire map rather than a camelCase re-spelling that has to be re-translated at the encode/decode boundary. Logical-field mapping (also mirrors the Python sibling Claim Pydantic model in AP00013 + the Go ome.Claim struct):

ws → workspace identifier id → claim id (uuidv7) sub → subject identifier par → parent claim ids (DAG) iss → issuer DID ch → content hash (SHA-256, 32 bytes) eh → embedding hash kn → ClaimKind ts → timestamp (Unix-ms, int64)

This is a PURE TYPE-SHAPE alignment (ENG-2279 Task 4, EVIDENCE): no runtime behavior changes — the verify kernel re-encodes the inner map verbatim as an opaque envelope and never reads these property names.

Properties

| Name | Type | Description | | --- | --- | --- | | ch | Uint8Array | ch — SHA-256 of the claim body (32 bytes). | | eh? | Uint8Array<ArrayBufferLike> | eh — SHA-256 of the embedding (32 bytes). Zero digest / absent = "no embedding". | | id | string | id — claim identifier (uuidv7 string; the Python sibling carries this as 16-byte UUIDv7 bytes). | | iss | string | iss — issuer DID URI (canonical W3C DID Core §3.2 form). | | kn | ClaimKind | kn — frozen v1 ClaimKind enum (per ADR-047). | | par | string[] | par — parent claim IDs (DAG; uuidv7 strings). Empty for assertions. | | sub | string | sub — subject identifier (typically a DID URI). | | ts | number | ts — Unix-ms; load-bearing for signature canonicalization (int64 wire). | | ws | string | ws — workspace identifier; a string CODE (e.g. WS-PROD1), NOT a uuid (design §3.4: typed str, no format constraint). |

ImportSummary

interface ImportSummary

Bundle import summary (v0.2 surface; placeholder type).

Returned by client.memory.importBundle() describing the result of a bundle import operation (claims accepted, rejected, duplicates).

Properties

| Name | Type | Description | | --- | --- | --- | | acceptedCount | number | Number of claims successfully imported | | duplicateCount | number | Number of claims skipped (already present) | | errors | Record<string, string> | Per-claim error map for rejected claims | | rejectedCount | number | Number of claims rejected (e.g., signature mismatch) |

InferenceArgs

interface InferenceArgs

Per-call inference arguments. Exactly one of prompt / messages must be set.

Properties

| Name | Type | Description | | --- | --- | --- | | maxTokens? | number | | | messages? | InferenceMessage[] | | | prompt? | string | | | stop? | string[] | | | temperature? | number | | | topP? | number | |

InferenceClientOptions

interface InferenceClientOptions

Construction options for InferenceClient.

Properties

| Name | Type | Description | | --- | --- | --- | | fetch? | (input: URL \| RequestInfo, init?: RequestInit) => Promise<Response> | Injectable fetch (for tests / custom transports). Defaults to global fetch. | | timeoutMs? | number | Stream timeout in milliseconds (default 120_000). Must be > 0. | | token? | string | Bearer JWT (the same token the gRPC OmeClient uses); the edge derives the workspace from it. | | workspaceId? | string | Optional os-workspace-id header hint. |

InferenceMessage

interface InferenceMessage

One OpenAI-shaped chat turn.

Properties

| Name | Type | Description | | --- | --- | --- | | content | string | | | role | string | |

InferenceResult

interface InferenceResult

The assembled outcome of a streamed inference.

output is the ordered concatenation of the delta tokens (the authoritative output the edge hashes into the OIR — ADR-286). oirB64 is the base64 OIR receipt when the gateway emitted one, else undefined (emit dark / not configured — NEVER a fabricated receipt; NO STUBS).

Properties

| Name | Type | Description | | --- | --- | --- | | finishReason? | string | | | oirB64? | string | | | output | string | | | usage? | TokenUsage | |

JmtProof

interface JmtProof

Jellyfish Merkle Tree proof (read-side).

Deprecated: Shape is PROVISIONAL — NOT the real 16-ary model. The real OME JMT proof is a 16-ary (radix-16) domain-tagged Jellyfish-Merkle-Tree proof (AP00011-OME-FILE-FORMAT-V1.md §13.x, ENG-1227 v1.0.3 spec-freeze), in which each internal node binds up to 15 sibling subtree digests — NOT a single flat sibling per level as the siblings: Uint8Array[] field below implies. verifyProof therefore throws OmeNotImplementedError: a faithful re-decider needs the 16-ary node hashing + the frozen domain prefixes + a Go/Java-minted JMT proof KAT (which does not yet exist) as its cross-language oracle. This interface is retained only so the v0.1 type surface compiles; it will be replaced by the real 16-ary shape when the proof KAT lands.

Wire-equivalent (once re-modeled) to:

• Python sibling: osyra_ome.types.JmtProof (AP00013)
• Go reference: jmt.Proof

Properties

| Name | Type | Description | | --- | --- | --- | | key | Uint8Array | Key (typically claim ID or content hash) | | leafExtension? | Uint8Array<ArrayBufferLike> | Leaf extension bytes (optional; for shorter-than-256-bit keys) | | root | Uint8Array | 32-byte tree root | | siblings | Uint8Array<ArrayBufferLike>[] | Sibling hashes from leaf to root (each 32 bytes) | | valueHash | Uint8Array | SHA-256 of the value at this key (32 bytes) |

MemoryNamespace

interface MemoryNamespace

memory namespace — read + write claim API. STATEFUL; requires kernel- copy for write-side; NDA-restricted distribution.

Methods

batchWrite(claims: Claim[]): Promise<string[]>

Batch-write claims via streaming RPC.

v0.2 surface — throws OmeNotImplementedError in v0.1.

exportBundle(workspaceId: string, path: string): Promise<BundleManifest>

Export a workspace bundle to a destination path.

v0.2 surface — throws OmeNotImplementedError in v0.1.

exportBundleManifest(ctx?: OmeMcpCallContext): Promise<OmeMcpBundleManifest>

Drain a real whole-workspace export and return its signed manifest.

getClaim(claimId: string, ctx?: OmeMcpCallContext): Promise<SignedClaim>

Retrieve a claim by ID via the real OME GetClaimBody RPC.

IMPLEMENTED RPC path (ENG-2585; public Edge route pending). Returns a SignedClaim VIEW with the server's stored body (as encodedCbor) + content_hash (as claim.ch), after a VERIFY-ON-READ binding check (SHA-256(body) MUST equal content_hash, else OmeWireFormatError). The GetClaimBody read path NEVER returns the Ed25519 signature (excluded structurally by the proto), so the view's signature/signerDid are EMPTY — the value the server actually returned, not a fabricated one.

Returns: Signed claim envelope view (body + content-hash; empty signature).

Throws: OmeWireFormatError on a non-UUID handle or a content-hash mismatch.

getClaimBody(claimId: string, ctx?: OmeMcpCallContext): Promise<OmeMcpClaimBody>

Truthful body/hash read projection; signature bytes are not on this RPC.

importBundle(path: string, targetWorkspace: string): Promise<ImportSummary>

Import a bundle into a target workspace.

v0.2 surface — throws OmeNotImplementedError in v0.1.

list(filter?: OmeMcpListFilter, ctx?: OmeMcpCallContext): Promise<OmeMcpListResult>

List server-sanitized claim handles using AP00011 keyset pagination.

tombstone(args: TombstoneArgs, ctx?: OmeMcpCallContext): Promise<TombstoneResult>

Tombstone (GDPR Art-17 crypto-erase) a claim — the net-new 4-arg signature (ENG-2570 / ARC-38 / ADR-296 D2). This is the leg the AP00015 tombstone EXECUTE foundation-gate (hasTombstoneSdk) waits on; the arg + return shapes are byte-for-byte the AP00015 TombstoneSdkArgs / TombstoneReceiptView.

The SDK validates the request CLIENT-SIDE before any transport (fail-closed): reasonCode in TombstoneArgs MUST name one of the supported reason-code values (UNSPECIFIED is never valid — OME rejects it OSY-MEM-5184); reasonDetail ≤256 UTF-8 bytes (NEVER include PII — hashed server-side); actorId ≤512 bytes; handle + workspaceId non-empty. Validation failures throw OmeWireFormatError synchronously-rejected (never reach the wire).

IMPLEMENTED RPC path (ENG-2585; public Edge route pending): once validated, the call invokes the OME Tombstone RPC (the handle is converted to 16 UUID bytes + the reason-code string to the proto enum; workspaceId is only a requested selector until Edge validates and re-stamps authoritative tenant context). A transport / server failure surfaces as a typed Ome*Error — it NEVER fabricates a receipt (fail-closed; ADR-296 forbids a faked erasure).

Returns: The rich TombstoneResult erasure receipt.

Throws: OmeWireFormatError on a client-side validation failure (bad reasonCode / oversized detail|actor / empty handle|workspace).

Throws: Ome*Error on a transport / server failure (never a fabricated receipt).

writeClaim(claim: Claim, ctx?: OmeMcpCallContext): Promise<string>

Write a claim to the workspace via the real OME SignAndInsert RPC (server-side KMS-signs the claim envelope + inserts the leaf into the per-workspace JMT in one fused call) and return the server-assigned uuidv7 claim id.

IMPLEMENTED RPC path (ENG-2585; public Edge route pending). Client-side validation runs first (a malformed claim throws OmeWireFormatError before the wire); a transport failure surfaces as a typed Ome*Error — never a fabricated id.

Returns: Claim ID (uuidv7) assigned by the server

Throws: OmeWireFormatError on a client-side validation failure (before the wire).

Throws: Ome*Error on a transport / server failure (never a fabricated id).

OirMessage

interface OirMessage

One chat message. V1 freezes the CLOSED {role, content} string-only shape.

Properties

| Name | Type | Description | | --- | --- | --- | | content | string | | | role | string | |

OirParams

interface OirParams

The CLOSED V1 generation-parameter set. undefined = "param not set" = OMITTED (omission is meaningful, so e.g. maxTokens: 0 is PRESENT, NOT omitted). stop absent (undefined) ≠ present-empty ([]). model_id is NOT here (OIR key 14). maxTokens / seed accept a bigint for values above 2^53 (e.g. 2^64-1).

Properties

| Name | Type | Description | | --- | --- | --- | | frequencyPenalty? | number | | | maxTokens? | number \| bigint | | | presencePenalty? | number | | | seed? | number \| bigint | | | stop? | string[] | | | temperature? | number | | | topP? | number | |

OmeAuthOptions

interface OmeAuthOptions

Authentication options. token is required and is the only request credential wired in the current release: the transport sends it as Authorization: Bearer ….

refreshToken and signingKey are reserved inputs. They are accepted only alongside token, captured privately, and redacted from the public options surface, but neither is consumed today: there is no automatic token refresh and no client-side request signing. signingKey is reserved for a v0.2+ request-signing surface. Construction without token — including a signing-key-only configuration — throws OmeAuthError.

Secret handling (F032): the secret-bearing fields (token, refreshToken, signingKey) are captured into a PRIVATE store inside OmeClient and are NOT exposed on the public client.options.auth surface. Reading client.options.auth.token / .refreshToken / .signingKey returns the redaction sentinel "[redacted]" (or the field is absent when it was not supplied), so a logged/serialized client.options never leaks the raw credential. Only the bearer token is read for transport authentication today; retaining a reserved field does not make it active.

Properties

| Name | Type | Description | | --- | --- | --- | | refreshToken? | string | Reserved for a future automatic-refresh flow. Captured and redacted, but never consumed by the current SDK; no automatic refresh occurs. | | signingKey? | string \| Uint8Array<ArrayBufferLike> | Reserved BYOK Ed25519 private key (32 raw bytes or a PEM string) for a v0.2+ request-signing surface. Captured and redacted, but never consumed by the current SDK; it does not sign or authenticate requests today. | | token | string | Required bearer token from Edge auth; the only wired request credential. |

OmeClientOptions

interface OmeClientOptions

OmeClient constructor options. Workspace + auth required; transport + verify + observability all optional with sensible defaults.

Properties

| Name | Type | Description | | --- | --- | --- | | auth | OmeAuthOptions | Authentication. token is required and is the only credential bound to requests today; refreshToken and signingKey are reserved/unwired. | | observability? | OmeObservabilityOptions | Observability hooks | | signer? | OmeSignerOptions | Non-exporting AP00011 signer identity + structured key reference. Required only for writeClaim; read-only clients may omit it. | | transport? | OmeTransportOptions | Transport config (defaults to api.osyra.ai:443, TLS=true). | | verifyLocally? | boolean | Defense-in-depth: re-verify Ed25519 signatures locally even when Edge has already verified. Default true per PM-BRIEF §3.2. | | workspace | string | Workspace identifier. A required, non-empty string. There is NO format constraint (design §4.1/§3.4: typed str, no validation): real workspaces are CODES (e.g. WS-PROD1), NOT uuids — do not assume a uuid shape. |

OmeObservabilityOptions

interface OmeObservabilityOptions

Observability hooks (optional).

Properties

| Name | Type | Description | | --- | --- | --- | | logger? | Pick<Console, "warn" \| "error" \| "info" \| "debug"> | Logger; defaults to console | | metricsCallback? | (metric: string, value: number, tags: Record<string, string>) => void | Per-call metrics callback | | tracer? | unknown | OpenTelemetry tracer (interface-compatible) |

OmeTransportOptions

interface OmeTransportOptions

Transport options. TLS-by-default (tls: true). Disabling TLS is FAIL-CLOSED: tls: false THROWS OmeTransportError at construction UNLESS the caller also sets allowInsecure: true (an explicit opt-in). This is the security-threat-model M2 mitigation enforced in code — a misconfiguration cannot silently downgrade the channel. There is NO external CI gate behind this; the guard lives entirely in this constructor.

Properties

| Name | Type | Description | | --- | --- | --- | | allowInsecure? | boolean | Explicit opt-in required to permit an insecure (tls: false) channel. Default false/undefined. When tls: false is set WITHOUT this flag the constructor THROWS OmeTransportError (insecure transport requires an explicit opt-in — fail-closed, M2). Intended ONLY for local test rigs against a plaintext loopback endpoint; never in production. | | caBundle? | string | Optional CA bundle path (system CA by default) | | endpoint? | string | Default: api.osyra.ai:443 (the public resource boundary). | | maxRetries? | number | Maximum retry count (default: 3) | | retryBackoffMs? | number | Initial backoff in ms (exponential; default: 100) | | shutdownGraceMs? | number | Graceful shutdown deadline in ms for client.close() / async dispose. Default: 5000 (design doc §4.3). Honored once Connect-RPC transport is wired (v0.1.0-alpha.2). HIGH-ARCH-SF5 fold-in. | | timeoutMs? | number | Per-call default timeout in ms (default: 30000) | | tls? | boolean | TLS toggle. Default true. Setting false is rejected at construction (throws OmeTransportError) UNLESS allowInsecure: true is also set. When opted in, a plaintext channel is used and a runtime warning is emitted (threat-model M2). NEVER set tls: false against production. |

ProofNamespace

interface ProofNamespace

proof namespace — JMT proof prove + verify.

Methods

prove(claimId: string): Promise<JmtProof>

Prove a claim's inclusion via JMT.

v0.2 surface — throws OmeNotImplementedError in v0.1.

verify(proof: JmtProof): Promise<boolean>

Verify a JMT proof. Alias for client.verify.proof() — delegates directly (per HIGH-ARCH-SF6 fold-in). This THROWS OmeNotImplementedError: client.verify.proof is shape-only and stays unwired until the cross-language 16-ary domain-tagged JMT proof KAT exists (ENG-1227 v1.0.3 spec-freeze). Proof verification fails closed rather than returning a verdict — a structural-walk "true" could green-light a forged proof.

ServerSpec

interface ServerSpec

ENG-2568 (ARC-36 / MCP-C-37 / ADR-292): the server-advertised OME spec identity. Returned by client.getServerSpec(); a client pins specId and fail-closes its startup binding on mismatch.

Properties

| Name | Type | Description | | --- | --- | --- | | region? | string | Backend residency region (e.g. "us-east-1"). May be empty. | | specId | string | The stable, frozen .ome v1 family spec identity (e.g. "urn:osyra:ome:v1"). | | specVersion? | string | Informational backend point release (e.g. "1.0.9"). May be empty. |

SignedClaim

interface SignedClaim

Signed claim envelope (canonical-CBOR wire form).

signature is Ed25519 (64 bytes) over canonical_cbor([tstr("osyra-ome- claim-v1"), payload]) per ome_service.proto §CANONICAL SIGNING PREIMAGE. encodedCbor is the bit-exact canonical-CBOR wire form — the bytes the Ed25519 signature covers. Signatures MUST be verified OVER encodedCbor VERBATIM (the wire bytes), NEVER re-derived by re-encoding claim (the wire-truth invariant — re-encoding can diverge from the signed bytes; this was the C1 verify-false bug). claim is a decoded VIEW, not signed.

Mirror of Python SignedClaim; mirror of Go ome.SignedClaim.

Properties

| Name | Type | Description | | --- | --- | --- | | claim | Claim | Decoded view of the signed claim | | encodedCbor | Uint8Array | Bit-exact canonical-CBOR wire bytes — the Ed25519 signing PREIMAGE (Form-B [tstr(dsTag), claimMap]). Cross-language interop surface — Java/Go/Python/TS encoders MUST produce byte-identical output for the same logical payload (per §12.6 cross-language contract test, GA-blocking). The detached signature is verified OVER these bytes verbatim (NOT re-encoded). | | signature | Uint8Array | Ed25519 signature (64 bytes) — proto SignedClaim.sig (field 3) | | signerDid | string | DID of the signing key (e.g., "did:osyra:key:...") | | signerPub? | Uint8Array<ArrayBufferLike> | Optional in-band 32-byte Ed25519 signer public key — proto SignedClaim.signer_pub (field 4). Empty / absent is the proto3-default "not populated" case (out-of-band DID resolution is preferred). NOT a trust anchor. client.verify.receipt does NOT use this field to establish authenticity: verifying a claim against its own embedded key is forgeable (anyone can self-sign and attach their public key). A relying party MUST supply an externally-anchored trustedPubKey (pinned key or out-of-band DID resolution). This field is retained because it is a real proto field (carried for transport / display / DID-resolution input). |

TokenUsage

interface TokenUsage

Token accounting reported on the terminal frame (best-effort display; may be absent).

Properties

| Name | Type | Description | | --- | --- | --- | | completionTokens | number | | | promptTokens | number | | | totalTokens | number | |

TombstoneArgs

interface TombstoneArgs

ENG-2570: the 4-arg tombstone() input (ADR-296 D2 — the net-new SDK signature the AP00015 tombstone EXECUTE foundation-gate (hasTombstoneSdk) waits on; the shape is byte-for-byte the AP00015 TombstoneSdkArgs).

Properties

| Name | Type | Description | | --- | --- | --- | | actorId | string | The acting principal (= cap sub, frozen at the SDK boundary; ≤512 bytes) — proto actor_id. | | handle | string | The claim handle (uuidv7 string) to tombstone — maps to proto claim_id (16-byte UUIDv7). | | reasonCode | TombstoneReasonCode | Enumerated reason (no free-text PII at the audit boundary) — proto reason_code. | | reasonDetail? | string | Optional detail (≤256 UTF-8 bytes; hashed server-side, NEVER include PII) — proto reason_detail. | | workspaceId | string | The workspace the handle lives in (server re-binds it authoritatively). |

TombstoneReceipt

interface TombstoneReceipt

Tombstone receipt (v0.2 surface; placeholder type).

Returned by client.memory.tombstone() after server commits a GDPR Art-17 erasure marker.

Properties

| Name | Type | Description | | --- | --- | --- | | claimId | string | Original claim ID being tombstoned | | encodedCbor | Uint8Array | Bit-exact canonical-CBOR wire bytes | | reason | string | Tombstone reason (e.g., "gdpr_art17") | | signature | Uint8Array | Signature over the tombstone preimage | | tombstoneMs | number | Unix-ms when the tombstone committed |

TombstoneResult

interface TombstoneResult

ENG-2570: the rich erasure receipt returned by the OME Tombstone RPC (mirrors TombstoneResponse + the AP00015 TombstoneReceiptView). The salt is NEVER on the wire (ENG-583 B-1/sec); the audit trail resolves via auditCorrelationId.

Properties

| Name | Type | Description | | --- | --- | --- | | auditCorrelationId | string | The MEMORY_TOMBSTONED audit-event correlation id (proto audit_correlation_id). | | newRoot | string | The workspace JMT root AFTER the tombstone landed, lowercase-hex (proto new_root). | | redactedAt | number | Unix-ms when the tombstone committed (proto redacted_at). | | tombstonedAtSequence | number | The post-tombstone durable sequence number (proto tombstoned_at_sequence). |

VerifyNamespace

interface VerifyNamespace

verify namespace — read-only verification. STATELESS; no kernel-copy required. Apache-2.0-shippable.

Methods

bundleManifest(coseSign1Bytes: Uint8Array, preimageBytes: Uint8Array, trustAnchors: Uint8Array<ArrayBufferLike>[]): Promise<boolean>

Verify a portable .ome bundle manifest's COSE_Sign1 signature.

v0.1 surface — ships fully wired.

Returns: true iff the COSE signature verifies under a trusted issuer.

proof(proof: JmtProof): Promise<boolean>

Verify a JMT proof inclusion.

NOT IMPLEMENTED in v0.1 — the real model is a 16-ary domain-tagged JMT proof; a Go/Java-minted proof KAT (ENG-1227 v1.0.3) is the prerequisite. Throws OmeNotImplementedError.

receipt(signed: SignedClaim, trustedPubKey?: Uint8Array<ArrayBufferLike>): Promise<boolean>

Verify a SignedClaim's DETACHED bare-Ed25519 signature over its wire preimage bytes.

The signature covers signed.encodedCbor (the Form-B preimage) VERBATIM — there is NO re-encode. A caller-supplied trustedPubKey is REQUIRED for an authenticity verdict: the in-band signed.signerPub is NOT a trust anchor (verifying a claim against its own embedded key is forgeable — anyone can self-sign). If trustedPubKey is omitted the call fails closed and THROWS (a receipt is never "verified" without an external trust anchor).

v0.1 surface — ships fully wired.

Returns: true iff the detached signature verifies over the preimage under the supplied trust anchor.

Throws: OmeWireFormatError when no trustedPubKey is supplied (fail-closed).

witness(preimageBytes: Uint8Array, signature: Uint8Array, trustedPubKey: Uint8Array, expectedRoot?: Uint8Array<ArrayBufferLike>): Promise<boolean>

Verify a Completeness Witness: a DETACHED bare-Ed25519 signature over the witness preimage bytes, with an optional committed-root check.

v0.1 surface — ships fully wired (gap-proof JMT leg deferred).

Witness

interface Witness

Completeness Witness (Phase 3 substrate).

Cryptographic proof that a workspace's append-only ledger has not been silently truncated or forked between two checkpoint times. Verified locally via Ed25519 + JMT proof chain.

Mirror of Python CompletenessWitness; mirror of Go ome.Witness.

Properties

| Name | Type | Description | | --- | --- | --- | | claimCount | number | Cardinality of claims in [startMs, endMs] | | encodedCbor | Uint8Array | Bit-exact canonical-CBOR wire bytes | | endMs | number | Upper-bound checkpoint Unix-ms (inclusive) | | root | Uint8Array | JMT root over the claims | | signature | Uint8Array | Ed25519 signature over the canonical signing payload | | signerDid | string | Witness signer DID | | startMs | number | Lower-bound checkpoint Unix-ms (inclusive) | | workspaceId | string | Workspace this witness covers |

WitnessNamespace

interface WitnessNamespace

witness namespace — Completeness Witness build + verify.

Methods

build(workspaceId: string): Promise<Witness>

Build a completeness witness for a workspace.

v0.2 surface — throws OmeNotImplementedError in v0.1.

verify(witness: Witness, trustedPubKey: Uint8Array): Promise<boolean>

Verify a completeness witness. Convenience wrapper over client.verify.witness() — delegates with witness.encodedCbor as the preimage, witness.signature as the detached signature, and witness.root as the expected committed root. A trusted Ed25519 public key MUST be supplied (a Witness carries no in-band key); fail-closed.

Type aliases

ClaimKind

type ClaimKind = "IngestClaim" | "DerivationClaim" | "TombstoneClaim" | "AttestationClaim" | "TransferClaim"

ClaimKind v1 floor (per ADR-047 ClaimKind Registry).

Frozen for V1 GA. New kinds added in V1.5+ via the DispatchKindRequest/DispatchKindResponse registry RPC.

CompatStatement

type CompatStatement = typeof __compat__

Type alias surfacing the const shape for downstream type-checking.

DsTag

type DsTag = typeof DS_TAG[keyof typeof DS_TAG]

OmeCallContext

type OmeCallContext = OmeMcpCallContext

Per-call context (design §4.2). Flows the deadline + correlation metadata for a single RPC. All fields optional — when requestId is omitted the SDK generates a uuidv4 x-request-id for end-to-end traceability (design §4.2 and ENG-180).

OmeErrorKind

type OmeErrorKind = "auth" | "workspace" | "policy" | "wire_format" | "verify" | "rate_limit" | "server" | "transport" | "bundle" | "not_found" | "quota" | "invalid_signature" | "malformed_cbor" | "not_implemented" | "unsupported_runtime" | "client_closed"

Error category discriminator. Stable across SDK versions; new variants appended at the end (existing values frozen for compatibility).

Includes both the verify-subset kinds (re-exported here) and the NDA-only kinds (defined below).

PolicyDecision

type PolicyDecision = "ALLOW" | "DENY" | "IMPLICIT_DENY"

ENG-2569 (ARC-36 / MCP-C-32/38 / ADR-291): the policy pre-flight verdict.

IMPLICIT_DENY is the FAIL-CLOSED sentinel — distinct from an explicit policy DENY — that an SDK/MCP caller treats identically to a deny (it marks "no affirmative ALLOW was obtained": unreachable enforcer / timeout / transport error / indeterminate). A transport error NEVER reads as ALLOW.

QuarantineClass

type QuarantineClass = "ok" | "signature_failed" | "stale_witness" | "policy_mismatch" | "wire_format_error"

Quarantine class for receipts that fail integrity checks.

Read-side enum; non-exhaustive on purpose (server may emit new values in V1.5+). Consumers must handle unknown variants defensively.

TombstoneReasonCode

type TombstoneReasonCode = "GDPR_ART17_DSAR" | "LEGAL_HOLD_EXPIRY" | "CUSTOMER_OFFBOARDING" | "OPERATOR_REDACTION" | "REGULATORY_OTHER"

ENG-2570 (ARC-38 / MCP-C-34/35 / ADR-296): the tombstone reason-code enum.

Mirrors the ome-proto TombstoneReasonCode (bare-string forms, byte-equivalent to the proto enum values 1..5). TOMBSTONE_REASON_UNSPECIFIED (0) is deliberately EXCLUDED — the OME Tombstone RPC rejects it (not_in: [0] / OSY-MEM-5184), so an UNSPECIFIED reason can never be a valid SDK input.

Functions

assembleOutput

assembleOutput(deltas: string[]): Uint8Array

Concatenate the raw UTF-8 bytes of each streamed delta in stream order — no separators, NO Unicode normalization. Byte-level so a multi-byte rune split across two deltas reassembles correctly.

| Parameter | Type | Description | | --- | --- | --- | | deltas | string[] | |

assembleOutputB64

assembleOutputB64(deltasB64: string[]): Uint8Array

Concatenate base64-decoded delta byte-fragments in stream order — for deltas that are NOT individually valid UTF-8 (a rune split across deltas), carried as base64 so no information is lost.

| Parameter | Type | Description | | --- | --- | --- | | deltasB64 | string[] | |

emptyCapSpecDigest

emptyCapSpecDigest(): Uint8Array

Re-derive the AP00016 polspec cap_spec_digest for the empty CapSpec {schema:1, grants:[], depth:0}: SHA-256(capDomainTag ‖ U16BE(schema) ‖ U64BE(depth=0) ‖ U64BE(|grants|=0)).

outputHash

outputHash(output: Uint8Array): Uint8Array

output_hash = SHA-256(output) — PLAIN, no domain tag (mirrors AP00016 RecomputeBinding).

| Parameter | Type | Description | | --- | --- | --- | | output | Uint8Array | |

paramsCbor

paramsCbor(p: OirParams): Uint8Array

CoreDet CBOR of the integer-keyed params map (only SET params present) — KAT-transparent.

| Parameter | Type | Description | | --- | --- | --- | | p | OirParams | |

paramsDigest

paramsDigest(p: OirParams): Uint8Array

params_digest = SHA-256(paramsDomainTag ‖ U16BE(schema) ‖ CoreDet-CBOR(params_map)).

| Parameter | Type | Description | | --- | --- | --- | | p | OirParams | |

promptHash

promptHash(preimage: Uint8Array): Uint8Array

prompt_hash = SHA-256(prompt_preimage).

| Parameter | Type | Description | | --- | --- | --- | | preimage | Uint8Array | |

promptPreimageMessages

promptPreimageMessages(messages: OirMessage[]): Uint8Array

form-1 preimage: the RFC 8785 JCS of the messages array.

| Parameter | Type | Description | | --- | --- | --- | | messages | OirMessage[] | |

promptPreimageString

promptPreimageString(prompt: string): Uint8Array

form-0 preimage for a single prompt string (raw UTF-8 body).

| Parameter | Type | Description | | --- | --- | --- | | prompt | string | |

verifyBundleManifest

verifyBundleManifest(coseSign1Bytes: Uint8Array, preimageBytes: Uint8Array, trustAnchors: Uint8Array<ArrayBufferLike>[]): Promise<boolean>

Verify a portable .ome bundle manifest's COSE_Sign1 signature.

The bundle signature is a COSE_Sign1 (RFC 9052), NOT a bare Ed25519 detached signature. Verification:

1. Decode coseSign1Bytes as the 4-tuple [protected(bstr), unprotected(map), payload(bstr), signature(bstr64)].
2. CONSTANT-TIME byte-equal the protected-header CONTENTS to A1 01 27 (alg = EdDSA) and assert the unprotected header is the canonical empty map (A0) — WITHOUT field-decoding either (algorithm-confusion defense). A mismatch is an algorithm-confusion rejection (OSY-MEM-5262 BUNDLE_UNEXPECTED_ALG).
3. Assert the COSE payload == preimageBytes (constant-time) — the caller-supplied 5-element Form-B array [tstr("osyra-ome-bundle-v1"), Manifest, TreeMetadata, ClaimsDigest, TombstoneDigest] MUST be exactly what the COSE envelope carries.
4. Build sign_input = canonical_cbor(["Signature1", protectedBstr, h'', payloadBstr]) with the tiny fixed-shape CBOR writer (NOT cbor-x, NOT the NDA write-side encoder).
5. Extract issuer_pub_keys from the Manifest (preimage element[1]).
6. Verify over ALL (issuer_pub_keys ∩ trustAnchors) with NO early-exit on the first match (so the loop does not leak WHICH anchor matched via early-return timing), accumulating a boolean; return true iff ANY anchor's Ed25519.verify(anchor, sign_input, coseSignature) holds.

Cross-language KAT: the V1 bundle vector — preimage.cbor, bundler-sig.cbor, issuer key d75a98…511a (V1.yaml issuer_pub_keys[0]).

Returns: true iff the COSE signature verifies under an anchor that is also an issuer; false on a genuine no-match verify-false.

Throws: OmeWireFormatError on a malformed COSE shape (OSY-MEM-5259 BUNDLE_SHAPE_MISMATCH), an algorithm-confusion header (OSY-MEM-5262 BUNDLE_UNEXPECTED_ALG), a payload != preimage echo mismatch (OSY-MEM-5263 BUNDLE_PREIMAGE_ECHO_MISMATCH), or a bad issuer_pub_keys field (OSY-MEM-5267 BUNDLE_ISSUER_KEYS_OVERFLOW).

Throws: OmeMalformedCborError on un-decodable / non-canonical CBOR.

Throws: OmeUnsupportedRuntimeError on missing native crypto backend.

| Parameter | Type | Description | | --- | --- | --- | | coseSign1Bytes | Uint8Array | The COSE_Sign1 envelope bytes (bundler-sig.cbor). | | preimageBytes | Uint8Array | The 5-element Form-B bundle preimage array bytes. | | trustAnchors | Uint8Array<ArrayBufferLike>[] | The relying party's set of trusted 32-byte Ed25519 public keys. An EMPTY set fails closed (no anchor → cannot verify). |

verifyEd25519

verifyEd25519(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): Promise<boolean>

Verify an Ed25519 signature against a public key and message.

Runtime dispatch:

• Node 20+ → node:crypto.verify (libuv → OpenSSL; constant-time)
• Workers / browser / Deno / Bun → crypto.subtle.verify (Ed25519 curve; constant-time per W3C WebCrypto Secure Curves draft)
• Neither available → OmeUnsupportedRuntimeError (hard refusal; JS scalar-mult fallback is REFUSED per PC-12 + R-NEW-17).

Defense-in-depth: this kernel never falls back to a non-constant-time implementation. If the runtime cannot provide a constant-time verify, callers must upgrade to a supported runtime or accept the failure.

Returns: true iff signature verifies under the public key + message

Throws: OmeInvalidSignatureError if signature or public key is malformed (wrong length).

Throws: OmeUnsupportedRuntimeError if no constant-time native backend is available in this runtime.

| Parameter | Type | Description | | --- | --- | --- | | signature | Uint8Array | 64-byte Ed25519 signature | | message | Uint8Array | Signing preimage (the bytes signed; e.g., canonical signing preimage) | | publicKey | Uint8Array | 32-byte Ed25519 public key (raw form) |

verifyOeraser

verifyOeraser(oeraserBody: Uint8Array, destructionAuthorityPubkeys: readonly Uint8Array<ArrayBufferLike>[], now: number | bigint): Promise<boolean>

Re-decide an OERaseR verified-forgetting receipt body, offline and fail-closed.

Re-derives the four legs (erasurePinned ∧ retentionPermits ∧ keyDestroyed ∧ noResurrection) + the erasure_binding terminal weld over the disclosed witnesses in oeraserBody, trusting ONLY the relying-party-pinned key-destruction authority set. Byte-identical to the Go reference (AP00016) + Java emitter (AP00011) + Python SDK (AP00013) — the frozen ENG-2316 KAT is the cross-language oracle.

Returns: A Promise resolving to true on a full accept (all four legs + the terminal weld passed). NEVER resolves false — every reject rejects the Promise (throws), so a caller cannot accidentally trust a receipt that did not fully re-decide.

Throws: OmeWireFormatError on a non-canonical body, a schema/field-length violation (OSY-EAT-6308), or invalid now / destructionAuthorityPubkeys.

Throws: OmeMalformedCborError on un-decodable CBOR (from the kernel decoder).

Throws: OmeVerifyError on a leg / terminal-weld failure — the message carries the same OSY-EAT-NNNN code the Go re-decider emits (6370 KEY_NOT_DESTROYED, 6371 RETENTION_FORBIDS, 6372 LEGAL_HOLD_ACTIVE, 6373 ERASURE_ROOT_MISMATCH, 6374 TOMBSTONE_INCONSISTENT, 6375 RESURRECTION_DETECTED, 6376 UNVERIFIABLE_POLICY).

| Parameter | Type | Description | | --- | --- | --- | | oeraserBody | Uint8Array | The canonical-CBOR oeraser-body bytes (§4.2.1) — the opaque EAT receipt body; the frozen ENG-2316 KAT unit. | | destructionAuthorityPubkeys | readonly Uint8Array<ArrayBufferLike>[] | The relying party's PINNED set of 32-byte raw Ed25519 key-destruction-authority public keys (rotation-tolerant — the attestation must verify under ANY one). An EMPTY set fails closed: with no pinned authority the keyDestroyed leg cannot be satisfied (KEY_NOT_DESTROYED). This is the trust anchor — the DPA pins the authority it trusts, NOT the controller's say-so. | | now | number \| bigint | The attested clock value (unsigned-64-bit seconds; number or bigint) the retention window is evaluated against. Supplied by the relying party; the re-decision never reads a clock of its own, so it is reproducible offline. |

verifyProof

verifyProof(_proof: JmtProof): Promise<boolean>

Verify a JMT proof of inclusion — NOT IMPLEMENTED.

The real model is a 16-ary (radix-16) domain-tagged Jellyfish-Merkle-Tree proof, NOT the flat sibling-list shape _types.ts JmtProof exposes. A faithful re-decider requires:

• the 16-ary node hashing (a leaf binds to up to 15 sibling subtree digests per internal node, NOT a single sibling per level),
• the domain-separation prefixes locked by the ENG-1227 v1.0.3 spec- freeze gate (AP00011-OME-FILE-FORMAT-V1.md §13.x),
• and a Go/Java-minted JMT proof KAT as the cross-language oracle, which does NOT yet exist.

Until a real KAT lands, returning a structural-walk "true" would be a stub that could green-light a forged proof — categorically forbidden. This throws OmeNotImplementedError. See ENG-1227 (v1.0.3 spec-freeze) for the prerequisite proof KAT.

Throws: OmeNotImplementedError always.

| Parameter | Type | Description | | --- | --- | --- | | _proof | JmtProof | A JMT proof object (shape is PROVISIONAL — see _types.ts). |

verifyReceipt

verifyReceipt(preimageBytes: Uint8Array, signature: Uint8Array, trustedPubKey: Uint8Array): Promise<boolean>

Verify a SignedClaim receipt: a DETACHED bare-Ed25519 signature over the wire preimage bytes.

Preimage = the wire bytes = the Form-B 2-tuple [tstr("osyra-ome-claim-v1"), claimMap] (9 CTAP2-sorted short-key entries: ws, id, sub, par, iss, ch, eh, kn, ts). The signature is a DETACHED sibling (NOT embedded in claimMap). Verify = Ed25519.verify(trustedPubKey, signature, preimageBytes) — NO re-encode.

Cross-language KAT: claim-preimage-kat-v1.json (Go reference oracle, ADR-157 Form-B 9-field short-key). Every vector's preimageHex must SHA-256 to preimageSha256 AND verify under the shared signerPubHex.

Returns: true iff signature verifies over preimageBytes; false on a genuine Ed25519 verify-false.

Throws: OmeMalformedCborError on empty / non-canonical / non-2-tuple bytes.

Throws: OmeWireFormatError on dsTag mismatch or wrong-length inputs.

Throws: OmeUnsupportedRuntimeError on missing native crypto backend.

| Parameter | Type | Description | | --- | --- | --- | | preimageBytes | Uint8Array | Raw wire preimage bytes (the bytes signed). | | signature | Uint8Array | 64-byte detached Ed25519 signature. | | trustedPubKey | Uint8Array | 32-byte trusted Ed25519 public key. |

verifyWitness

verifyWitness(preimageBytes: Uint8Array, signature: Uint8Array, trustedPubKey: Uint8Array, expectedRoot?: Uint8Array<ArrayBufferLike>): Promise<boolean>

Verify a Completeness Witness: a DETACHED bare-Ed25519 signature over the wire preimage bytes, with an optional decoded-root check.

Preimage = the Form-B 2-tuple [tstr("osyra-ome-cw-v1"), cwMap]. Verify = bare Ed25519.verify(pub, sig, preimageBytes) — like the receipt — NO re-encode. The Ed25519 signature gate runs FIRST (security M2 / WitnessVerifier.java ordering): the decoded root of an UNAUTHENTICATED witness is never inspected. ONLY AFTER the signature verifies, if expectedRoot is supplied, the decoded root field of the cwMap is constant-time-compared to it — an authenticated witness committing to an unexpected root is a legitimate NEGATIVE verdict (returns false), not a wire-format throw.

If the witness carries a non-empty gap_proofs field, this throws OmeNotImplementedError — the gap-proof JMT leg is deferred (no KAT exists).

NO cross-language witness KAT exists yet; the test suite uses a SYNTHETIC vector minted from a fixed seed (documented in tests/kat/verify-v1/PROVENANCE.md).

Returns: true iff signature verifies AND (if given) the committed root matches; false on a genuine verify-false OR an authenticated-but-wrong-root witness.

Throws: OmeMalformedCborError on empty / non-canonical / non-2-tuple bytes.

Throws: OmeWireFormatError on dsTag mismatch, a non-Uint8Array expectedRoot, or an authenticated witness missing a byte-string root when expectedRoot is supplied.

Throws: OmeNotImplementedError if the witness carries gap_proofs.

| Parameter | Type | Description | | --- | --- | --- | | preimageBytes | Uint8Array | Raw wire preimage bytes (the bytes signed). | | signature | Uint8Array | 64-byte detached Ed25519 signature. | | trustedPubKey | Uint8Array | 32-byte trusted Ed25519 public key. | | expectedRoot | Uint8Array<ArrayBufferLike> | Optional 32-byte root the witness MUST commit to. |

Variables

DS_TAG

const DS_TAG: { BUNDLE: "osyra-ome-bundle-v1"; CLAIM: "osyra-ome-claim-v1"; GRANT: "osyra-ome-grant-v1"; TOMBSTONE_SALT: "osyra-ome-tombstone-salt-v1"; WITNESS: "osyra-ome-cw-v1" }

Domain-separation tags (per ome_service.proto §CANONICAL SIGNING PREIMAGE).

Each signed envelope type has a distinct dsTag prefix in its CBOR preimage so an Ed25519 signature over a Claim cannot be replayed as a signature over a Witness. Wire-frozen at OAP-MEM v1.0 RFC.

TOMBSTONE_REASON_CODES

const TOMBSTONE_REASON_CODES: readonly TombstoneReasonCode[]

The complete set of accepted TombstoneReasonCode string values — the runtime allowlist the SDK validates tombstone() input against (fail-closed: an unknown reason code never reaches the wire).

VERSION

const VERSION: "1.0.0"

Public version constant.

Mirror of osyra_ome.__version__ from the Python sibling SDK (AP00013-osyra-ome-sdk-python). Bumped per CHANGELOG.md (Keep a Changelog).

__compat__

const __compat__: { adapters: { langchain: ">=0.3" }; apiVersion: "0.1"; crossLanguageParity: { parityGate: "ADR-045-beta-extension"; pythonSibling: "osyra_ome"; pythonSiblingMinVersion: "0.1.0" }; v1_1_typescript_planned: readonly ["langgraph"]; v1_python_only: readonly ["langgraph", "llamaindex", "autogen"]; wireFormat: { name: "OAP-MEM"; supported: readonly [">=0.1", "<0.2"] } }

Cross-port compatibility statement. Frozen-as-const for tree-shake friendliness AND so the type system surfaces the exact adapter list to downstream code (no string fallback).