@motebit/protocol 0.8.0 → 1.0.0

package/dist/computer-use.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Computer-use payload types — wire format for `computer-use-v1.md`.
+ *
+ * A motebit with a desktop surface (Tauri) can observe and act on the user's
+ * computer: screenshot, move, click, type, scroll. This spec pins the wire
+ * format of each action and observation so the signed audit trail is
+ * implementation-agnostic — a non-TypeScript verifier can validate payloads
+ * against the committed JSON Schema rather than TypeScript's structural view.
+ *
+ * Shape: actions are a **nested discriminated union** (`action: { kind, ... }`)
+ * not a flat envelope. Impossible states are structurally unrepresentable —
+ * drag-only fields never appear on a click, type-only fields never appear on
+ * a scroll. Cross-language SDKs (Rust enums, Python tagged unions) map
+ * directly; JSON Schema emits clean `oneOf` branches; model output stays
+ * rigorous.
+ *
+ * Observation results carry **artifact references** (`artifact_id +
+ * artifact_sha256`) not inline bytes. The receipt artifact store (see
+ * `spec/execution-ledger-v1.md`) holds the bytes; the observation payload
+ * binds to them by hash. Keeps signed receipts O(bytes of metadata) instead
+ * of O(bytes of image). Git / IPFS / S3+hash pattern.
+ *
+ * Every type named here is referenced by a `### X.Y — Name` section under a
+ * `#### Wire format (foundation law)` block in `spec/computer-use-v1.md`,
+ * so `check-spec-coverage` (invariant #9) keeps the spec and types in
+ * lockstep.
+ *
+ * ── Release status ───────────────────────────────────────────────────
+ *
+ * Every export in this file carries `@alpha` — the wire format was revised
+ * on 2026-04-22 in response to external principal review (commit 54158b11,
+ * flat envelope → nested discriminated union) and has only soaked inside
+ * the monorepo since. `@alpha` carves these types out of `@motebit/protocol`'s
+ * SemVer contract for the 1.x series: the `check-api-surface` baseline still
+ * tracks their shape so unintended drift is caught, but a shape reshape does
+ * not force a major bump. Promote to `@beta` → `@public` once a second
+ * producer (cloud-browser surface, federation peer replaying an audit log)
+ * or a non-desktop-shim consumer exercises the format in anger.
+ */
+/**
+ * A point in primary-display logical pixel coordinates. `(0, 0)` = top-left.
+ * @alpha
+ */
+export interface ComputerPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Optional semantic target information attached to pointer actions. When
+ * available from the accessibility layer or DOM, it lets verifiers and
+ * approval UX explain "motebit clicked the Send button" instead of only
+ * "(512, 384)". Execution still happens at the pixel coordinates in
+ * `target`; the hint is advisory.
+ * @alpha
+ */
+export interface ComputerTargetHint {
+    /** Role name. Examples: `"button"`, `"link"`, `"textbox"`, `"menuitem"`. */
+    readonly role?: string;
+    /** Accessible label or visible text. */
+    readonly label?: string;
+    /**
+     * Where the hint came from. `"accessibility"` (OS AX API), `"dom"`
+     * (browser inspection), `"vision"` (OCR/ML), `"user_annotation"` (user
+     * labeled the region in-session).
+     */
+    readonly source: string;
+}
+/**
+ * Capture the primary display's current frame.
+ * @alpha
+ */
+export interface ScreenshotAction {
+    readonly kind: "screenshot";
+}
+/**
+ * Read the current cursor coordinates.
+ * @alpha
+ */
+export interface CursorPositionAction {
+    readonly kind: "cursor_position";
+}
+/**
+ * Single mouse click at `target`.
+ * @alpha
+ */
+export interface ClickAction {
+    readonly kind: "click";
+    readonly target: ComputerPoint;
+    /** `"left" | "right" | "middle"`. Defaults to `"left"`. */
+    readonly button?: string;
+    /** Subset of `["cmd", "ctrl", "alt", "shift"]`. */
+    readonly modifiers?: readonly string[];
+    readonly target_hint?: ComputerTargetHint;
+}
+/**
+ * Two clicks in rapid succession at `target`.
+ * @alpha
+ */
+export interface DoubleClickAction {
+    readonly kind: "double_click";
+    readonly target: ComputerPoint;
+    readonly button?: string;
+    readonly modifiers?: readonly string[];
+    readonly target_hint?: ComputerTargetHint;
+}
+/**
+ * Move cursor to `target` without clicking.
+ * @alpha
+ */
+export interface MouseMoveAction {
+    readonly kind: "mouse_move";
+    readonly target: ComputerPoint;
+    readonly target_hint?: ComputerTargetHint;
+}
+/**
+ * Press at `from`, move to `to`, release.
+ * @alpha
+ */
+export interface DragAction {
+    readonly kind: "drag";
+    readonly from: ComputerPoint;
+    readonly to: ComputerPoint;
+    readonly button?: string;
+    readonly modifiers?: readonly string[];
+    /** Total drag duration in ms. Implementation may interpolate intermediate points. */
+    readonly duration_ms?: number;
+    readonly target_hint?: ComputerTargetHint;
+}
+/**
+ * Keyboard text input.
+ * @alpha
+ */
+export interface TypeAction {
+    readonly kind: "type";
+    readonly text: string;
+    /**
+     * Per-character delay in ms. Omitted = implementation default. Set to a
+     * stable value for deterministic replay of typing cadence.
+     */
+    readonly per_char_delay_ms?: number;
+}
+/**
+ * Keyboard combination. Example: `"cmd+c"`, `"ctrl+shift+t"`, `"escape"`.
+ * @alpha
+ */
+export interface KeyAction {
+    readonly kind: "key";
+    readonly key: string;
+}
+/**
+ * Scroll at `target` by `(dx, dy)` wheel deltas.
+ * @alpha
+ */
+export interface ScrollAction {
+    readonly kind: "scroll";
+    readonly target: ComputerPoint;
+    readonly dx: number;
+    readonly dy: number;
+}
+/**
+ * Full action taxonomy. Every concrete action the motebit can request is
+ * one of these. Exhaustive discriminated union on `kind`.
+ * @alpha
+ */
+export type ComputerAction = ScreenshotAction | CursorPositionAction | ClickAction | DoubleClickAction | MouseMoveAction | DragAction | TypeAction | KeyAction | ScrollAction;
+/**
+ * Discriminator values — useful for JSON Schema enum and runtime validation.
+ * @alpha
+ */
+export declare const COMPUTER_ACTION_KINDS: readonly ["screenshot", "cursor_position", "click", "double_click", "mouse_move", "drag", "type", "key", "scroll"];
+/** @alpha */
+export type ComputerActionKind = (typeof COMPUTER_ACTION_KINDS)[number];
+/**
+ * One invocation of the `computer` tool. The `action` field holds a nested
+ * discriminated variant; all action-specific fields live inside that
+ * object. Impossible states are structurally unrepresentable.
+ * @alpha
+ */
+export interface ComputerActionRequest {
+    /** Open session the action belongs to. */
+    readonly session_id: string;
+    readonly action: ComputerAction;
+}
+/**
+ * Outcome of a successful observation action's execution. Returned as the
+ * `data` field of a `ToolResult`. Discriminated by `kind`.
+ * @alpha
+ */
+export type ComputerObservationResult = ScreenshotObservation | CursorPositionObservation;
+/**
+ * Structured redaction metadata. Replaces a bare boolean — a verifier can
+ * now prove *what* was redacted, under *which* policy version, and whether
+ * the bytes the AI saw are raw or a projection.
+ * @alpha
+ */
+export interface ComputerRedaction {
+    /** `true` iff any region was classified as sensitive and masked. */
+    readonly applied: boolean;
+    /**
+     * Projection shape of the bytes the AI consumed. `"raw"` = unmodified
+     * capture, `"masked"` = regions replaced with solid fill,
+     * `"blurred"` = regions convolved, `"cropped"` = sensitive regions
+     * removed from frame. Surfaces MAY add projection kinds in v1.1.
+     */
+    readonly projection_kind: string;
+    /** Version string of the sensitivity-classification policy that ran. */
+    readonly policy_version?: string;
+    /** Number of regions classified as sensitive in the raw frame. */
+    readonly classified_regions_count?: number;
+    /**
+     * SHA-256 digest of a canonical JSON array of classified regions
+     * (each region: `{ x, y, w, h, classification }`). Lets a verifier
+     * replay what was masked without exposing the region list in the
+     * receipt if policy dictates.
+     */
+    readonly classified_regions_digest?: string;
+}
+/**
+ * Screenshot observation. Bytes live in the receipt artifact store keyed
+ * by `artifact_id` and bound by `artifact_sha256`. When redaction produces
+ * a distinct projection (e.g. masked image), both the raw and projection
+ * artifact IDs are referenced so a verifier can fetch either depending on
+ * authorization.
+ * @alpha
+ */
+export interface ScreenshotObservation {
+    readonly kind: "screenshot";
+    readonly session_id: string;
+    /** Artifact ID of the raw capture in the artifact store. */
+    readonly artifact_id: string;
+    /** SHA-256 of the raw capture's bytes. */
+    readonly artifact_sha256: string;
+    /** `"png" | "jpeg"`. */
+    readonly image_format: string;
+    /** Image width in logical pixels. */
+    readonly width: number;
+    /** Image height in logical pixels. */
+    readonly height: number;
+    /** Unix ms of the capture. */
+    readonly captured_at: number;
+    readonly redaction: ComputerRedaction;
+    /**
+     * Artifact ID of the redacted projection, when `redaction.applied` and
+     * the projection differs from the raw capture. When absent, the AI saw
+     * the raw bytes (redaction.projection_kind === "raw").
+     */
+    readonly projection_artifact_id?: string;
+    /** SHA-256 of the projection bytes. Paired with `projection_artifact_id`. */
+    readonly projection_artifact_sha256?: string;
+}
+/**
+ * Cursor-position observation — single coordinate pair.
+ * @alpha
+ */
+export interface CursorPositionObservation {
+    readonly kind: "cursor_position";
+    readonly session_id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly captured_at: number;
+}
+/**
+ * Signed event emitted when a computer-use session begins. Carries the
+ * primary display's dimensions and scaling factor so the AI knows the
+ * coordinate space subsequent actions will operate in.
+ *
+ * `display_width` and `display_height` are logical pixels (the dimensions
+ * action coordinates live in). `scaling_factor` is the logical-to-physical
+ * ratio (Retina = 2.0). Screenshot dimensions returned in observations
+ * match the logical dimensions, not the physical raster.
+ * @alpha
+ */
+export interface ComputerSessionOpened {
+    readonly session_id: string;
+    readonly motebit_id: string;
+    readonly display_width: number;
+    readonly display_height: number;
+    readonly scaling_factor: number;
+    readonly opened_at: number;
+}
+/**
+ * Signed event emitted when a computer-use session ends.
+ * @alpha
+ */
+export interface ComputerSessionClosed {
+    readonly session_id: string;
+    readonly closed_at: number;
+    /** Free-text code. Examples: `"user_closed"`, `"timeout"`, `"error"`. */
+    readonly reason?: string;
+}
+/**
+ * Structured failure reasons a computer-use action may return. Every
+ * implementation MUST emit one of these (or a v1.1-extended value) on
+ * failure so the motebit's reasoning loop and the governance audit can
+ * discriminate cases deterministically.
+ *
+ *   policy_denied      — governance classified the action as deny
+ *   approval_required  — governance classified as require_approval; no consent yet
+ *   approval_expired   — consent was obtained but its window elapsed
+ *   permission_denied  — OS refused (e.g. no Screen Recording permission on macOS)
+ *   session_closed     — action fired outside an open session
+ *   target_not_found   — element at `target` coords no longer exists (accessibility-verified fail)
+ *   target_obscured    — element exists but is covered (menu over it, etc.)
+ *   user_preempted     — physical user input interrupted mid-dispatch
+ *   platform_blocked   — OS blocked synthetic input (secure password field, elevation boundary)
+ *   not_supported      — surface cannot execute computer use at all
+ * @alpha
+ */
+export declare const COMPUTER_FAILURE_REASONS: readonly ["policy_denied", "approval_required", "approval_expired", "permission_denied", "session_closed", "target_not_found", "target_obscured", "user_preempted", "platform_blocked", "not_supported"];
+/** @alpha */
+export type ComputerFailureReason = (typeof COMPUTER_FAILURE_REASONS)[number];
+//# sourceMappingURL=computer-use.d.ts.map

package/dist/computer-use.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computer-use.d.ts","sourceRoot":"","sources":["../src/computer-use.ts"],"names":[],"mappings":"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"}

package/dist/computer-use.js

@@ -0,0 +1,86 @@
+/**
+ * Computer-use payload types — wire format for `computer-use-v1.md`.
+ *
+ * A motebit with a desktop surface (Tauri) can observe and act on the user's
+ * computer: screenshot, move, click, type, scroll. This spec pins the wire
+ * format of each action and observation so the signed audit trail is
+ * implementation-agnostic — a non-TypeScript verifier can validate payloads
+ * against the committed JSON Schema rather than TypeScript's structural view.
+ *
+ * Shape: actions are a **nested discriminated union** (`action: { kind, ... }`)
+ * not a flat envelope. Impossible states are structurally unrepresentable —
+ * drag-only fields never appear on a click, type-only fields never appear on
+ * a scroll. Cross-language SDKs (Rust enums, Python tagged unions) map
+ * directly; JSON Schema emits clean `oneOf` branches; model output stays
+ * rigorous.
+ *
+ * Observation results carry **artifact references** (`artifact_id +
+ * artifact_sha256`) not inline bytes. The receipt artifact store (see
+ * `spec/execution-ledger-v1.md`) holds the bytes; the observation payload
+ * binds to them by hash. Keeps signed receipts O(bytes of metadata) instead
+ * of O(bytes of image). Git / IPFS / S3+hash pattern.
+ *
+ * Every type named here is referenced by a `### X.Y — Name` section under a
+ * `#### Wire format (foundation law)` block in `spec/computer-use-v1.md`,
+ * so `check-spec-coverage` (invariant #9) keeps the spec and types in
+ * lockstep.
+ *
+ * ── Release status ───────────────────────────────────────────────────
+ *
+ * Every export in this file carries `@alpha` — the wire format was revised
+ * on 2026-04-22 in response to external principal review (commit 54158b11,
+ * flat envelope → nested discriminated union) and has only soaked inside
+ * the monorepo since. `@alpha` carves these types out of `@motebit/protocol`'s
+ * SemVer contract for the 1.x series: the `check-api-surface` baseline still
+ * tracks their shape so unintended drift is caught, but a shape reshape does
+ * not force a major bump. Promote to `@beta` → `@public` once a second
+ * producer (cloud-browser surface, federation peer replaying an audit log)
+ * or a non-desktop-shim consumer exercises the format in anger.
+ */
+/**
+ * Discriminator values — useful for JSON Schema enum and runtime validation.
+ * @alpha
+ */
+export const COMPUTER_ACTION_KINDS = [
+    "screenshot",
+    "cursor_position",
+    "click",
+    "double_click",
+    "mouse_move",
+    "drag",
+    "type",
+    "key",
+    "scroll",
+];
+// ── Outcome taxonomy ─────────────────────────────────────────────────
+/**
+ * Structured failure reasons a computer-use action may return. Every
+ * implementation MUST emit one of these (or a v1.1-extended value) on
+ * failure so the motebit's reasoning loop and the governance audit can
+ * discriminate cases deterministically.
+ *
+ *   policy_denied      — governance classified the action as deny
+ *   approval_required  — governance classified as require_approval; no consent yet
+ *   approval_expired   — consent was obtained but its window elapsed
+ *   permission_denied  — OS refused (e.g. no Screen Recording permission on macOS)
+ *   session_closed     — action fired outside an open session
+ *   target_not_found   — element at `target` coords no longer exists (accessibility-verified fail)
+ *   target_obscured    — element exists but is covered (menu over it, etc.)
+ *   user_preempted     — physical user input interrupted mid-dispatch
+ *   platform_blocked   — OS blocked synthetic input (secure password field, elevation boundary)
+ *   not_supported      — surface cannot execute computer use at all
+ * @alpha
+ */
+export const COMPUTER_FAILURE_REASONS = [
+    "policy_denied",
+    "approval_required",
+    "approval_expired",
+    "permission_denied",
+    "session_closed",
+    "target_not_found",
+    "target_obscured",
+    "user_preempted",
+    "platform_blocked",
+    "not_supported",
+];
+//# sourceMappingURL=computer-use.js.map

package/dist/computer-use.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"computer-use.js","sourceRoot":"","sources":["../src/computer-use.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAyJH;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,YAAY;IACZ,iBAAiB;IACjB,OAAO;IACP,cAAc;IACd,YAAY;IACZ,MAAM;IACN,MAAM;IACN,KAAK;IACL,QAAQ;CACA,CAAC;AAwIX,wEAAwE;AAExE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,eAAe;IACf,mBAAmB;IACnB,kBAAkB;IAClB,mBAAmB;IACnB,gBAAgB;IAChB,kBAAkB;IAClB,iBAAiB;IACjB,gBAAgB;IAChB,kBAAkB;IAClB,eAAe;CACP,CAAC"}

package/dist/credential-anchor.d.ts

@@ -1,8 +1,9 @@
 /**
  * Credential anchor types — motebit/credential-anchor@1.0.
  *
- * MIT: these types define the interoperable format for credential anchoring.
- * Any implementation can produce and verify anchor proofs using these types.
+ * Permissive floor (Apache-2.0): these types define the interoperable format
+ * for credential anchoring. Any implementation can produce and verify anchor
+ * proofs using these types.
  */
 /** A batch of credential hashes anchored as a Merkle tree. */
 export interface CredentialAnchorBatch {
@@ -18,6 +19,13 @@ export interface CredentialAnchorBatch {
     first_issued_at: number;
     /** Millisecond timestamp of the latest credential in the batch. */
     last_issued_at: number;
+    /**
+     * Cryptosuite discriminator. Always `"motebit-jcs-ed25519-hex-v1"` —
+     * JCS canonicalization of the unsigned batch payload, Ed25519
+     * primitive, hex signature encoding, hex public-key encoding.
+     * Verifiers reject missing or unknown suite values fail-closed.
+     */
+    suite: "motebit-jcs-ed25519-hex-v1";
     /** Hex-encoded Ed25519 signature over the canonical batch payload. */
     signature: string;
     /** Onchain anchor metadata, or null if signed but not yet submitted. */
@@ -60,6 +68,13 @@ export interface CredentialAnchorProof {
     relay_id: string;
     /** Hex-encoded Ed25519 public key of the relay (for signature verification). */
     relay_public_key: string;
+    /**
+     * Cryptosuite discriminator for `batch_signature`. Always
+     * `"motebit-jcs-ed25519-hex-v1"` — JCS canonicalization of the batch
+     * payload, Ed25519 primitive, hex signature encoding, hex public-key
+     * encoding. Verifiers reject missing or unknown suite values fail-closed.
+     */
+    suite: "motebit-jcs-ed25519-hex-v1";
     /** Hex-encoded Ed25519 signature over the canonical batch payload. */
     batch_signature: string;
     /** Onchain anchor metadata, or null if not yet submitted. */

package/dist/credential-anchor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credential-anchor.d.ts","sourceRoot":"","sources":["../src/credential-anchor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACtC;AAED,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oDAAoD;IACpD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACtC;AAID;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChG,8EAA8E;IAC9E,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC"}
+{"version":3,"file":"credential-anchor.d.ts","sourceRoot":"","sources":["../src/credential-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,KAAK,EAAE,4BAA4B,CAAC;IACpC,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACtC;AAED,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oDAAoD;IACpD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,KAAK,EAAE,4BAA4B,CAAC;IACpC,sEAAsE;IACtE,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACtC;AAID;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChG,8EAA8E;IAC9E,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC"}

package/dist/credential-anchor.js

@@ -1,8 +1,9 @@
 /**
  * Credential anchor types — motebit/credential-anchor@1.0.
  *
- * MIT: these types define the interoperable format for credential anchoring.
- * Any implementation can produce and verify anchor proofs using these types.
+ * Permissive floor (Apache-2.0): these types define the interoperable format
+ * for credential anchoring. Any implementation can produce and verify anchor
+ * proofs using these types.
  */
 export {};
 //# sourceMappingURL=credential-anchor.js.map

package/dist/credential-anchor.js.map

@@ -1 +1 @@
-{"version":3,"file":"credential-anchor.js","sourceRoot":"","sources":["../src/credential-anchor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"credential-anchor.js","sourceRoot":"","sources":["../src/credential-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/crypto-suite.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Cryptosuite registry — the protocol's open set of verification recipes.
+ *
+ * A cryptosuite is the complete specification of how a signature is
+ * produced and verified for a class of artifacts: which algorithm,
+ * which canonicalization, which signature and key encodings. Matches
+ * the pattern of W3C VC 2.0 (`cryptosuite: "eddsa-jcs-2022"`) and
+ * COSE/JOSE algorithm registries — one ID per full recipe, not just
+ * "which primitive."
+ *
+ * Every signed wire-format artifact in motebit MUST carry a `suite`
+ * field (see each artifact's `#### Wire format (foundation law)`
+ * subsection in `spec/*.md`). Verifiers dispatch on the suite value.
+ * Missing or unknown suites are rejected fail-closed. See the
+ * `check-suite-declared` (spec-side) and `check-suite-dispatch`
+ * (code-side) drift gates.
+ *
+ * Post-quantum migration becomes a new registry entry + dispatch arm
+ * in `@motebit/crypto/suite-dispatch.ts`, not a wire-format change.
+ *
+ * Permissive floor (Apache-2.0), type-only, zero runtime deps.
+ */
+/**
+ * The closed set of suite identifiers motebit currently supports.
+ *
+ * Four Ed25519 suites cover the four canonicalization/encoding bundles
+ * already used in the codebase (exploration 2026-04-13 found these
+ * were genuinely distinct recipes, not one). The fifth entry is the
+ * W3C standard suite used by Verifiable Credentials.
+ *
+ * Adding a new suite is an intentional protocol-level change: new
+ * string literal here, new dispatch arm in `verifyBySuite`, new
+ * `SUITE_REGISTRY` entry, a changeset bump, and (typically) a new spec
+ * paragraph naming which artifacts adopt it.
+ */
+export type SuiteId = "motebit-jcs-ed25519-b64-v1" | "motebit-jcs-ed25519-hex-v1" | "motebit-jwt-ed25519-v1" | "motebit-concat-ed25519-hex-v1" | "eddsa-jcs-2022";
+/**
+ * Lifecycle status for each registered suite. Prevents today's bundles
+ * from calcifying into accidental permanent doctrine when PQ suites
+ * land — a demotion path is declared up front.
+ *
+ * - `preferred`: signers SHOULD emit under this suite; verifiers accept.
+ * - `allowed`: verifiers accept; signers MAY emit but `preferred` is
+ *   recommended. Used during transition windows.
+ * - `legacy`: verifiers accept; signers MUST NOT emit. Migration-only.
+ */
+export type SuiteStatus = "preferred" | "allowed" | "legacy";
+/**
+ * The primitive signature algorithm family. Separate from the suite
+ * name because several bundles share Ed25519 today, and the PQ world
+ * will introduce algorithms (ML-DSA-44, ML-DSA-65, SLH-DSA-SHA2-128s)
+ * that will each appear in multiple encoding variants.
+ */
+export type SuiteAlgorithm = "Ed25519" | "ML-DSA-44" | "ML-DSA-65" | "SLH-DSA-SHA2-128s";
+/** Canonicalization used to produce signed bytes. */
+export type SuiteCanonicalization = "jcs" | "json-stringify" | "utf8-concat";
+/** On-wire encoding of the signature string. */
+export type SuiteSignatureEncoding = "base64url" | "hex" | "multibase-base58btc";
+/** On-wire encoding of the public key reference carried alongside the signature. */
+export type SuitePublicKeyEncoding = "hex" | "multibase-did-key";
+/**
+ * The complete verification recipe for one suite. Metadata is readable
+ * by verifiers and by documentation / CLI tooling; the dispatcher in
+ * `@motebit/crypto/suite-dispatch.ts` is the authority on actual
+ * verification semantics.
+ */
+export interface SuiteEntry {
+    readonly id: SuiteId;
+    readonly algorithm: SuiteAlgorithm;
+    readonly canonicalization: SuiteCanonicalization;
+    readonly signatureEncoding: SuiteSignatureEncoding;
+    readonly publicKeyEncoding: SuitePublicKeyEncoding;
+    readonly status: SuiteStatus;
+    /**
+     * Short prose description — surfaces in tooling (e.g. CLI `motebit
+     * inspect`), spec cross-references, and error messages.
+     */
+    readonly description: string;
+}
+export declare const SUITE_REGISTRY: Readonly<Record<SuiteId, SuiteEntry>>;
+/**
+ * Type guard — narrows `unknown` or arbitrary strings to `SuiteId`.
+ * Verifiers MUST call this before dispatching; an unchecked cast is a
+ * fail-open path that the `check-suite-dispatch` gate will flag.
+ */
+export declare function isSuiteId(value: unknown): value is SuiteId;
+/**
+ * Look up a suite entry. Returns `undefined` for unknown IDs so
+ * callers can decide rejection semantics at their boundary (verifiers
+ * reject fail-closed; tooling may display "unknown suite").
+ */
+export declare function getSuiteEntry(id: SuiteId): SuiteEntry;
+export declare function getSuiteEntry(id: string): SuiteEntry | undefined;
+/**
+ * Canonical list of all registered suite IDs, frozen. Consumers that
+ * need to iterate (tooling, docs, tests) should use this instead of
+ * `Object.keys(SUITE_REGISTRY)` so TypeScript sees the narrow union.
+ */
+export declare const ALL_SUITE_IDS: readonly SuiteId[];
+//# sourceMappingURL=crypto-suite.d.ts.map

package/dist/crypto-suite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-suite.d.ts","sourceRoot":"","sources":["../src/crypto-suite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,OAAO,GACf,4BAA4B,GAC5B,4BAA4B,GAC5B,wBAAwB,GACxB,+BAA+B,GAC/B,gBAAgB,CAAC;AAErB;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,mBAAmB,CAAC;AAEzF,qDAAqD;AACrD,MAAM,MAAM,qBAAqB,GAC7B,KAAK,GACL,gBAAgB,GAChB,aAAa,CAAC;AAElB,gDAAgD;AAChD,MAAM,MAAM,sBAAsB,GAC9B,WAAW,GACX,KAAK,GACL,qBAAqB,CAAC;AAE1B,oFAAoF;AACpF,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,mBAAmB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,qBAAqB,CAAC;IACjD,QAAQ,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;IACnD,QAAQ,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAmD/D,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,CAAC;AACvD,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAKlE;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,OAAO,EAM1C,CAAC"}