@motebit/protocol 1.2.0 → 1.3.0

package/dist/transparency.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Operator-transparency declaration — the trust-anchor primitive.
+ *
+ * The motebit relay publishes a signed declaration of its observability
+ * posture at `/.well-known/motebit-transparency.json`. The declaration
+ * commits the operator to one Ed25519 public key (`relay_public_key`)
+ * and to the operator-defined `content` payload. Verifiers pin that
+ * key as the trust anchor for every other relay-asserted artifact:
+ * content-artifact manifests on state-export endpoints, settlement
+ * receipts the operator counter-signs, federation handshakes.
+ *
+ * This module exports the binding wire types per
+ * `spec/relay-transparency-v1.md` (2b-i, the trust-anchor primitive).
+ * The operator-comparison vocabulary (Stage 2b-ii — retention/processor
+ * field standardization) is deferred until a second motebit-compatible
+ * operator forces field standardization; the `content` field stays
+ * operator-defined here and verifiers MUST NOT reject declarations on
+ * unknown `content` fields.
+ *
+ * Doctrine: `docs/doctrine/operator-transparency.md`,
+ * `docs/doctrine/nist-alignment.md` §8 "savant gap closure",
+ * `docs/doctrine/self-attesting-system.md`.
+ *
+ * Permissive floor (Apache-2.0), type-only, zero runtime deps.
+ */
+import type { SuiteId } from "./crypto-suite.js";
+/**
+ * The pinned cryptosuite for transparency declarations. JCS
+ * canonicalization (RFC 8785) + Ed25519 + hex signature encoding.
+ * Matches the identity-file + credential-anchor + content-artifact
+ * family. See `SUITE_REGISTRY` in `./crypto-suite.ts`.
+ */
+export declare const TRANSPARENCY_SUITE: SuiteId;
+/**
+ * Canonical memo prefix the relay emits when anchoring the
+ * declaration hash to Solana via the Memo program. Full memo shape:
+ * `motebit:transparency:v1:{hash_hex}`. Verifiers scan for this
+ * prefix at the relay's pinned anchor address. See
+ * `spec/relay-transparency-v1.md` §5.2.
+ */
+export declare const TRANSPARENCY_ANCHOR_MEMO_PREFIX: "motebit:transparency:v1:";
+/**
+ * Current spec identifier. Bumps require explicit doctrine alignment
+ * + a new wire-format spec doc — the verifier MUST reject declarations
+ * with unrecognized `spec` values.
+ */
+export declare const TRANSPARENCY_SPEC_ID: "motebit-transparency/draft-2026-04-14";
+/**
+ * Operator-transparency declaration — the trust-anchor envelope.
+ *
+ * Wire format (foundation law) — see `spec/relay-transparency-v1.md` §3.1
+ * for the binding shape. Field names, types, and the canonical-JSON
+ * ordering of the signed payload are protocol law. The `content` field
+ * is operator-extensible — the protocol commits to the envelope, not
+ * to the posture vocabulary inside `content`.
+ *
+ * Hash derivation: `sha256(utf8(canonicalJson({spec, declared_at,
+ * relay_id, relay_public_key, content})))` — the post-sign fields
+ * `hash`, `suite`, `signature` are NOT included in the canonical bytes.
+ * Two implementations that hash the same payload MUST produce the same
+ * hex string byte-for-byte. Per `spec/relay-transparency-v1.md` §4.
+ */
+export interface SignedTransparencyDeclaration {
+    /** Spec identifier — e.g. `"motebit-transparency/draft-2026-04-14"`. Bump on breaking schema changes. */
+    readonly spec: string;
+    /** Epoch milliseconds when the declaration was minted. */
+    readonly declared_at: number;
+    /** Relay's identity — same MotebitId space as agent identities. */
+    readonly relay_id: string;
+    /** Hex-encoded Ed25519 public key (32 bytes / 64 chars). */
+    readonly relay_public_key: string;
+    /**
+     * Operator-defined posture payload — retention, processors,
+     * jurisdiction, honest gaps. Opaque to the protocol. Verifiers MUST
+     * NOT reject declarations on unknown `content` fields. Cross-operator
+     * comparison vocabulary is deferred to Stage 2b-ii.
+     */
+    readonly content: unknown;
+    /** Hex-encoded SHA-256 of the canonical-JSON of the signed payload. */
+    readonly hash: string;
+    /** Cryptosuite identifier — `motebit-jcs-ed25519-hex-v1` today. */
+    readonly suite: SuiteId;
+    /** Hex-encoded Ed25519 signature over the canonical-JSON of the signed payload. */
+    readonly signature: string;
+}
+/**
+ * The five-field signed payload — what `hash` and `signature` cover.
+ * Exposed as a type so producers can construct + canonicalize the
+ * exact bytes the verifier checks against. The post-sign fields
+ * (`hash`, `suite`, `signature`) are appended AFTER signing and are
+ * NOT part of this payload.
+ */
+export type TransparencySignedPayload = Pick<SignedTransparencyDeclaration, "spec" | "declared_at" | "relay_id" | "relay_public_key" | "content">;
+/**
+ * Onchain anchor record — the verifier's view of a memo found at the
+ * relay's pinned anchor address. Returned by
+ * `@motebit/state-export-client::lookupTransparencyAnchor` on success.
+ * Per `spec/relay-transparency-v1.md` §5.
+ */
+export interface TransparencyAnchorRecord {
+    /** Solana transaction signature containing the anchor memo. */
+    readonly tx_hash: string;
+    /** Anchored hash (the declaration's `hash` field at time of anchoring), lowercase hex. */
+    readonly anchored_hash_hex: string;
+    /** Solana address (base58 pubkey) where the anchor lives. Pinned out-of-band by the verifier. */
+    readonly anchor_address: string;
+}
+/**
+ * Type guard — narrows `unknown` to `SignedTransparencyDeclaration`.
+ * Structural shape only; does NOT verify the signature, anchor, or
+ * succession chain. Verifiers call this before parsing then proceed
+ * through the verification algorithm in `spec/relay-transparency-v1.md`
+ * §4.1.
+ */
+export declare function isSignedTransparencyDeclaration(value: unknown): value is SignedTransparencyDeclaration;
+//# sourceMappingURL=transparency.d.ts.map

package/dist/transparency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transparency.d.ts","sourceRoot":"","sources":["../src/transparency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAsC,CAAC;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,EAAG,0BAAmC,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAG,uCAAgD,CAAC;AAErF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,6BAA6B;IAC5C,yGAAyG;IACzG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,6BAA6B,EAC7B,MAAM,GAAG,aAAa,GAAG,UAAU,GAAG,kBAAkB,GAAG,SAAS,CACrE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,iGAAiG;IACjG,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,6BAA6B,CAaxC"}

package/dist/transparency.js

@@ -0,0 +1,67 @@
+/**
+ * Operator-transparency declaration — the trust-anchor primitive.
+ *
+ * The motebit relay publishes a signed declaration of its observability
+ * posture at `/.well-known/motebit-transparency.json`. The declaration
+ * commits the operator to one Ed25519 public key (`relay_public_key`)
+ * and to the operator-defined `content` payload. Verifiers pin that
+ * key as the trust anchor for every other relay-asserted artifact:
+ * content-artifact manifests on state-export endpoints, settlement
+ * receipts the operator counter-signs, federation handshakes.
+ *
+ * This module exports the binding wire types per
+ * `spec/relay-transparency-v1.md` (2b-i, the trust-anchor primitive).
+ * The operator-comparison vocabulary (Stage 2b-ii — retention/processor
+ * field standardization) is deferred until a second motebit-compatible
+ * operator forces field standardization; the `content` field stays
+ * operator-defined here and verifiers MUST NOT reject declarations on
+ * unknown `content` fields.
+ *
+ * Doctrine: `docs/doctrine/operator-transparency.md`,
+ * `docs/doctrine/nist-alignment.md` §8 "savant gap closure",
+ * `docs/doctrine/self-attesting-system.md`.
+ *
+ * Permissive floor (Apache-2.0), type-only, zero runtime deps.
+ */
+/**
+ * The pinned cryptosuite for transparency declarations. JCS
+ * canonicalization (RFC 8785) + Ed25519 + hex signature encoding.
+ * Matches the identity-file + credential-anchor + content-artifact
+ * family. See `SUITE_REGISTRY` in `./crypto-suite.ts`.
+ */
+export const TRANSPARENCY_SUITE = "motebit-jcs-ed25519-hex-v1";
+/**
+ * Canonical memo prefix the relay emits when anchoring the
+ * declaration hash to Solana via the Memo program. Full memo shape:
+ * `motebit:transparency:v1:{hash_hex}`. Verifiers scan for this
+ * prefix at the relay's pinned anchor address. See
+ * `spec/relay-transparency-v1.md` §5.2.
+ */
+export const TRANSPARENCY_ANCHOR_MEMO_PREFIX = "motebit:transparency:v1:";
+/**
+ * Current spec identifier. Bumps require explicit doctrine alignment
+ * + a new wire-format spec doc — the verifier MUST reject declarations
+ * with unrecognized `spec` values.
+ */
+export const TRANSPARENCY_SPEC_ID = "motebit-transparency/draft-2026-04-14";
+/**
+ * Type guard — narrows `unknown` to `SignedTransparencyDeclaration`.
+ * Structural shape only; does NOT verify the signature, anchor, or
+ * succession chain. Verifiers call this before parsing then proceed
+ * through the verification algorithm in `spec/relay-transparency-v1.md`
+ * §4.1.
+ */
+export function isSignedTransparencyDeclaration(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const o = value;
+    return (typeof o.spec === "string" &&
+        typeof o.declared_at === "number" &&
+        typeof o.relay_id === "string" &&
+        typeof o.relay_public_key === "string" &&
+        "content" in o &&
+        typeof o.hash === "string" &&
+        typeof o.suite === "string" &&
+        typeof o.signature === "string");
+}
+//# sourceMappingURL=transparency.js.map

package/dist/transparency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transparency.js","sourceRoot":"","sources":["../src/transparency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAY,4BAA4B,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,0BAAmC,CAAC;AAEnF;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,uCAAgD,CAAC;AAoErF;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B,CAC7C,KAAc;IAEd,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;QACjC,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;QAC9B,OAAO,CAAC,CAAC,gBAAgB,KAAK,QAAQ;QACtC,SAAS,IAAI,CAAC;QACd,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAC3B,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAChC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motebit/protocol",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Motebit protocol — identity, receipts, credentials, delegation, settlement, and trust algebra for sovereign AI agents. Types, semirings, routing primitives. Apache-2.0, zero dependencies.",
   "type": "module",
   "main": "./dist/index.js",