@adastracomputing/ink 0.1.0-alpha.3 → 0.1.1

package/CHANGELOG.md

@@ -8,6 +8,48 @@ here. Pre-1.0 releases follow `0.Y.Z` semantics, see
 
 No unreleased changes.
 
+## 0.1.1, discovery rename and normative SSRF floor
+
+This release is **wire-compatible with v0.1.0**; the wire version stays `ink/0.1`. Every change below is additive and accepts the prior shape for the duration of the v0.1.x line — implementations that emit and consume v0.1.0 cards / service entries continue to interoperate. One observable library behavior changes: the runtime emit value of the redacted Agent Card `type` field flips from `"tulpa.agent.card"` to `"ink.agent.card"` (see below). Consumers that pinned to the literal must accept either string; the TypeScript union has been widened accordingly.
+
+**Service entry rename.** The DID Document service entry for INK endpoints is now `type: "INKAgentEndpoint"`. The legacy `"TulpaAgentEndpoint"` is still accepted by consumers during v0.1.x; new publishers SHOULD emit `INKAgentEndpoint`. When both are present, `INKAgentEndpoint` takes precedence. Removed at the next wire-version bump.
+
+**Service entry now points at the Agent Card URL.** `serviceEndpoint` is the URL of the Agent Card, not the inbound message endpoint. Inbound URL stays on the Card itself in the `endpoint` field. Per the spec update, `inboxEndpoint` is also accepted as a synonym for `endpoint`.
+
+**Normative SSRF floor for discovery fetches.** The Discovery spec now mandates HTTPS-only, refusal of private/link-local/loopback/cloud-metadata hosts, bounded redirects with host re-checking on each hop, response size and time caps, and honoring `Cache-Control`. Detailed hardening stays implementer responsibility but the normative floor lives in the spec.
+
+**Normative DID-binding of fetched cards.** Consumers MUST bind the card's `ownerDid` (when present) to the DID under resolution, and bind the card's `agentId` to the agent identifier being sent to. A mismatch on either field is a hard reject. This closes the substitution attack where a host that legitimately publishes one DID claims to publish another.
+
+**Cache and refresh rules lifted into normative Discovery.** Refresh on signature/keyId miss, on observed `keySetVersion` increase, never fall back to bootstrap keys after a valid card has been observed.
+
+**Redacted Agent Card type renamed.** The `type` field on a redacted Agent Card is now `"ink.agent.card"`. Consumers MUST also accept the legacy `"tulpa.agent.card"` during v0.1.x. The `network.tulpa.*` wire-message types are explicitly **frozen** for v0.x per the compatibility policy; rewriting them would break every deployed router.
+
+**Wire version is `ink/0.1`.** All v0.1.x package releases emit `protocol: "ink/0.1"` on the wire. The next wire-version bump is `ink/0.2`.
+
+## 0.1.0-alpha.5, ship compiled JS
+
+Fixes a publish-time regression in `0.1.0-alpha.3` (and the unreleased
+`alpha.4`) where the package shipped raw TypeScript under `main` and
+`exports`. Node 24 refuses to strip types from anything under
+`node_modules`, so any consumer following the quickstart hit
+`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` on the first `import`
+and could not use the library at all.
+
+### Changed
+
+- `npm run build` compiles `src/` to `dist/` via `tsconfig.build.json`;
+  `prepublishOnly` runs it automatically so the npm tarball always
+  contains compiled JS plus declaration maps.
+- `main`, `types` and `exports."."` now point at `./dist/index.js` and
+  `./dist/index.d.ts`. The `files` array ships `dist/` instead of
+  `src/`, so consumers no longer see raw TS in `node_modules`.
+- Dev shell and `engines.node` move from Node 22 to Node 24 (the
+  current Active LTS) to match CI.
+
+End-to-end verified against `witness-demo.tulpa.network`: the
+quickstart `submit.mjs` now returns a signed inclusion receipt on
+Node 24 without modification.
+
 ## 0.1.0-alpha.3, signed audit-query response
 
 Closes the last HIGH conformance-audit finding (witness audit-query

package/README.md

@@ -29,7 +29,7 @@ INK assumes [AT Protocol](https://atproto.com) for identity by default but isn't
 npm install @adastracomputing/ink
 ```
 
-The package ships TypeScript sources directly. Consumers need a TS-aware toolchain (tsx, ts-node, esbuild, Vite, etc.).
+The package ships compiled ESM with bundled type definitions (`dist/index.js` + `dist/index.d.ts`). Any project with a standard JS toolchain can import it directly — no TypeScript build step on the consumer side. The build runs automatically via `prepack` before publish.
 
 ```ts
 import {
@@ -69,6 +69,12 @@ For consumers of bilateral audit-exchange responses (`network.tulpa.audit_respon
 
 For consumers of witness audit-query responses (`network.tulpa.audit_query_response`, Auditability §7.3, added in `0.1.0-alpha.3`), call `verifyAuditQueryResponse({response, witnessPublicKey, expectedRequester, expectedMessageId, verifyEventSignature, expectedServiceDid?, laterCheckpoint?})`. The `verifyEventSignature` callback is REQUIRED: it resolves the submitting agent's Ed25519 keys (typically via Agent Card §2) and validates each event's `agentSignature`. Without it, the verifier refuses to return valid, because Merkle inclusion alone does not prove a real agent produced the event (§7.5). The verifier enforces envelope shape, the `requester` binding (prevents cross-requester replay), events/proofs strict one-to-one alignment, the §7.4 per-event scope rule, walks every Merkle proof via `computeAuditMerkleLeafHash` up to the response's `rootHash`, runs `verifyEventSignature` on every event and supports an optional later-checkpoint cross-check. The lower-level `verifyAuditQueryResponseSignature` is signature-only and is not sufficient to accept a witness response on its own.
 
+## Agent-assisted implementation
+
+If you are asking an AI coding agent to add INK support to an existing service, the canonical packet for that workflow is the [Agent-assisted implementation](https://ink.tulpa.network/guides/agent-assisted-implementation/) guide. It contains the curated implementer prompt, a mandatory traceability matrix, the conformance checklist, and a human-review checklist. The guide is updated as the protocol evolves; treat it as the live source rather than copying its contents into your repo.
+
+Adopters who want the second open implementation to cross-check against can use the [`examples/foreign-sender-receiver/`](examples/foreign-sender-receiver/) TypeScript reference and the [`examples/interop-cli/`](examples/interop-cli/) Python from-scratch sender.
+
 ## Tests
 
 ```bash
@@ -78,7 +84,7 @@ npm run lint        # eslint
 npm run check:surface   # public-surface drift check
 ```
 
-For Nix users: `nix develop` gives a pinned Node 22 + git + gitleaks shell. `nix build` produces the publishable npm tarball under `result/`. `nix run github:Ad-Astra-Computing/ink -- verify-inclusion --file receipt.json --witness https://witness.example.com` runs the CLI without installing anything globally.
+For Nix users: `nix develop` gives a pinned Node 24 + git + gitleaks shell. `nix build` produces the publishable npm tarball under `result/`. `nix run github:Ad-Astra-Computing/ink -- verify-inclusion --file receipt.json --witness https://witness.example.com` runs the CLI without installing anything globally.
 
 ## Layout
 
@@ -95,7 +101,7 @@ test-vectors/  JSON interop vectors
 test/          vitest unit + integration tests
 ```
 
-The library runs on any runtime providing standard Web Crypto and `fetch`: Node 22+, Deno, Bun, Cloudflare Workers, browsers. The timestamp freshness window is enforced inside `verifyInkAuth`; nonce single-use is enforced when a `NonceStore` is passed (otherwise `checkReplay` must be called separately). Nonce backing storage and its TTL policy are the integrator's choice.
+The library runs on any runtime providing standard Web Crypto and `fetch`: Node 24+, Deno, Bun, Cloudflare Workers, browsers. The timestamp freshness window is enforced inside `verifyInkAuth`; nonce single-use is enforced when a `NonceStore` is passed (otherwise `checkReplay` must be called separately). Nonce backing storage and its TTL policy are the integrator's choice.
 
 ## What's stable in v0.1
 
@@ -121,6 +127,12 @@ You will see `network.tulpa.*` on the wire (e.g. `network.tulpa.intent`) and `in
 
 INK is developed by [Ad Astra Computing](https://adastracomputing.com) as the underlying protocol for [Tulpa](https://tulpa.network). The spec and the library in this repo are deliberately free of Tulpa product code so other agent platforms can adopt INK without inheriting Tulpa's surface area. Tulpa's product integration (message orchestration, marketplace, user-facing APIs) lives in a separate, closed-source codebase.
 
+## Interoperability
+
+INK is a wire protocol. Any compatible service that publishes a DID and exposes an `/ink/v1/...` endpoint can accept signed envelopes from agents that live on other platforms — cross-platform interop is a primary design goal.
+
+[`tulpa.network`](https://tulpa.network) is one current example of an accepting endpoint. Its receive side resolves inbound senders against published Agent Cards and applies operator-level and per-user acceptance policies; see [docs.tulpa.network/guide/foreign-agents](https://docs.tulpa.network/guide/foreign-agents/) for how a Tulpa user opts in. The protocol is intended to support other accepting endpoints.
+
 ## Security
 
 See [`SECURITY.md`](SECURITY.md) for the disclosure path. The threat model is in [`docs/threat-model.md`](docs/threat-model.md). **Do not open a public issue for security problems.**

package/dist/audit/inclusion-receipt.d.ts

@@ -0,0 +1,142 @@
+export interface InclusionReceipt {
+    eventId: string;
+    leafIndex: number;
+    treeSize: number;
+    rootHash: string;
+    inclusionProof: string[];
+    /** ISO 8601 timestamp at which the witness committed the leaf. */
+    timestamp: string;
+    /** Base64url Ed25519 signature over the canonical bytes. */
+    serviceSignature: string;
+}
+export interface VerifyStep {
+    name: string;
+    pass: boolean;
+    detail?: string;
+}
+export interface InclusionReceiptVerifyResult {
+    valid: boolean;
+    steps: VerifyStep[];
+}
+/**
+ * Verify an INK inclusion receipt.
+ *
+ * Always performs:
+ *  - Structural validation of the receipt object
+ *  - Service signature verification against `witnessPublicKey`
+ *
+ * Optionally performs (when the corresponding input is provided):
+ *  - Leaf-to-root proof walk (`eventHash`)
+ *  - Cross-check against a later signed checkpoint (`laterCheckpoint`)
+ */
+export declare function verifyInclusionReceipt(opts: {
+    receipt: InclusionReceipt;
+    /** Raw 32-byte Ed25519 public key of the witness service. */
+    witnessPublicKey: Uint8Array;
+    /** Optional RFC 6962 leaf hash for the underlying audit event:
+     *  SHA-256(0x00 || JCS(event-without-agentSignature)), hex-encoded.
+     *  Use `computeAuditMerkleLeafHash` to derive it. When provided, the
+     *  inclusion proof is walked from this leaf up to the claimed rootHash. */
+    eventHash?: string;
+    /** Optional later checkpoint to cross-check the receipt against.
+     *  Must come from a `/ink/v1/checkpoint` response that the verifier
+     *  has separately validated as authentic. */
+    laterCheckpoint?: {
+        treeSize: number;
+        rootHash: string;
+    };
+}): Promise<InclusionReceiptVerifyResult>;
+export interface AuditQueryResponse {
+    protocol: "ink/0.1";
+    type: "network.tulpa.audit_query_response";
+    serviceDid: string;
+    messageId: string;
+    requester: string;
+    events: Array<Record<string, unknown> & {
+        id: string;
+    }>;
+    proofs: Array<{
+        eventId: string;
+        leafIndex: number;
+        inclusionProof: string[];
+    }>;
+    treeSize: number;
+    rootHash: string;
+    timestamp: string;
+    serviceSignature: string;
+}
+export interface AuditQueryResponseVerifyResult {
+    valid: boolean;
+    steps: VerifyStep[];
+}
+/**
+ * Full §7.3 verification of a witness audit-query response. Use this in
+ * preference to `verifyAuditQueryResponseSignature`, which is the
+ * underlying primitive and verifies only the Ed25519 signature. This
+ * function additionally enforces:
+ *
+ *  - Envelope shape (protocol, type, serviceDid, requester, messageId,
+ *    timestamp, treeSize, rootHash, events[], proofs[])
+ *  - Service signature with the right canonical bytes
+ *  - Optional caller-supplied bindings: expected `messageId`,
+ *    `requester`, `serviceDid` (each rejected on mismatch)
+ *  - `events` and `proofs` align one-to-one by `eventId`
+ *  - Every event includes a non-empty `agentSignature` field
+ *  - Every proof walks from `computeAuditMerkleLeafHash(event)` up to
+ *    the response's `rootHash` at `treeSize`
+ *  - Optional `laterCheckpoint`: tree only grew, no fork at same size
+ *
+ * **Per-event agent-signature verification (§7.5 trust model).** A
+ * Merkle-valid response is necessary but not sufficient: the witness
+ * could in principle commit a fabricated "event" not signed by any
+ * agent, sign the resulting `(treeSize, rootHash)`, and the Merkle
+ * proof walks just fine. To detect this, callers MUST pass a
+ * `verifyEventSignature` callback that resolves the agent's published
+ * Ed25519 keys (typically via Agent Card §2) and validates
+ * `event.agentSignature`. The callback is REQUIRED, not optional: the
+ * verifier refuses to return `valid: true` without it, so a caller
+ * cannot accidentally accept witness-fabricated events.
+ *
+ * **Freshness.** A `valid: true` result attests that the response was a
+ * complete enumeration of the requester's visible events at the
+ * `(treeSize, rootHash)` snapshot the witness signed, NOT that it is
+ * the witness's current authoritative view. The signed envelope binds
+ * `timestamp`, but verifiers wanting "is this still current?"
+ * semantics MUST additionally fetch a fresh witness checkpoint and
+ * compare it (e.g. require `laterCheckpoint.treeSize === response.treeSize
+ * && laterCheckpoint.rootHash === response.rootHash` for "current", or
+ * use `laterCheckpoint` here only to prove the tree never rewound or
+ * forked).
+ *
+ * Returns `{valid, steps}` where each step explains pass/fail with detail.
+ * Pure function. Does not perform network I/O.
+ */
+export declare function verifyAuditQueryResponse(opts: {
+    response: AuditQueryResponse;
+    /** Raw 32-byte Ed25519 public key of the witness service. */
+    witnessPublicKey: Uint8Array;
+    /** Locally authenticated requester DID. Verifier MUST supply this so
+     *  a response signed for Alice cannot be replayed to Bob. */
+    expectedRequester: string;
+    /** The `messageId` the verifier asked about. Bound for paranoia: the
+     *  signed envelope already commits to messageId, so this catches
+     *  client-side routing bugs before they become trust bugs. */
+    expectedMessageId: string;
+    /** Optional: witness DID the verifier expects (pinned out of band). */
+    expectedServiceDid?: string;
+    /** Optional later checkpoint to cross-check against. Same semantics
+     *  as `verifyInclusionReceipt`. */
+    laterCheckpoint?: {
+        treeSize: number;
+        rootHash: string;
+    };
+    /** Per-event agent-signature verifier (REQUIRED by Auditability §7.5).
+     *  The caller resolves the event's submitting agent's public key set
+     *  (typically from the Agent Card) and returns true if
+     *  `event.agentSignature` verifies. The verifier refuses to return
+     *  `valid: true` without this: Merkle inclusion alone does not prove
+     *  the agent produced the event. If a caller genuinely wants to
+     *  bypass per-event signature checks (e.g. during a pure Merkle
+     *  audit), they MUST explicitly pass a callback that does so. */
+    verifyEventSignature: (event: Record<string, unknown>) => Promise<boolean>;
+}): Promise<AuditQueryResponseVerifyResult>;