@adastracomputing/ink 0.1.0-alpha.5 → 0.1.1

package/CHANGELOG.md

@@ -8,6 +8,24 @@ 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

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/index.d.ts

@@ -8,5 +8,6 @@ export { verifyInclusionReceipt, verifyAuditQueryResponse, type InclusionReceipt
 export { HandshakeBudgetTracker } from "./ink/handshake-budget.js";
 export type { InkSignInput } from "./crypto/ink.js";
 export type { CandidateKey } from "./models/key-entry.js";
+export { resolveAgentInbox } from "./models/agent-card.js";
 export type { AgentCard } from "./models/agent-card.js";
 export type { BudgetCheckResult, HandshakeBudgetConfig, } from "./ink/handshake-budget.js";

package/dist/index.js

@@ -13,3 +13,4 @@ export { verifyInkAuth } from "./middleware/ink-auth.js";
 export { verifyInclusionReceipt, verifyAuditQueryResponse, } from "./audit/inclusion-receipt.js";
 // Optional containment / governance primitives
 export { HandshakeBudgetTracker } from "./ink/handshake-budget.js";
+export { resolveAgentInbox } from "./models/agent-card.js";

package/dist/ink/discovery-gating.d.ts

@@ -10,8 +10,17 @@ import { z } from "zod";
 import { type AgentCard } from "../models/agent-card.js";
 import type { AgentCardVisibility } from "../models/ink-handshake.js";
 export { AgentCardVisibilitySchema, type AgentCardVisibility } from "../models/ink-handshake.js";
+/**
+ * The redacted Agent Card returned by visibility-aware GETs.
+ *
+ * The `type` field's canonical value is `"ink.agent.card"` from
+ * INK v0.1.1 onward. The legacy value `"tulpa.agent.card"` MUST
+ * also be accepted by consumers during the v0.1.x window so old
+ * publishers (and older snapshots of this library) keep parsing.
+ * The legacy synonym is removed at the next wire-version bump.
+ */
 export interface RedactedAgentCard {
-    type: "tulpa.agent.card";
+    type: "ink.agent.card" | "tulpa.agent.card";
     version: "1.0";
     agentId: string;
     displayName?: string;
@@ -77,6 +86,7 @@ export declare const AgentCardResponseSchema: z.ZodObject<{
         handle: z.ZodString;
         displayName: z.ZodString;
         endpoint: z.ZodString;
+        inboxEndpoint: z.ZodOptional<z.ZodString>;
         publicKeyMultibase: z.ZodString;
         profileSnapshot: z.ZodOptional<z.ZodObject<{
             headline: z.ZodString;

package/dist/ink/discovery-gating.js

@@ -25,7 +25,10 @@ export function buildRedactedCard(card) {
     // the field is anything other than the known enum members.
     const visibility = card.visibility === "network_only" ? "network_only" : "capability_gated";
     const out = {
-        type: "tulpa.agent.card",
+        // INK v0.1.1+: emit the protocol-generic name. The interface
+        // union accepts both so consumers that hold pre-v0.1.1 cached
+        // values keep parsing.
+        type: "ink.agent.card",
         version: "1.0",
         agentId: card.agentId,
         displayName: card.displayName,

package/dist/models/agent-card.d.ts

@@ -13,6 +13,7 @@ export declare const AgentCardSchema: z.ZodObject<{
     handle: z.ZodString;
     displayName: z.ZodString;
     endpoint: z.ZodString;
+    inboxEndpoint: z.ZodOptional<z.ZodString>;
     publicKeyMultibase: z.ZodString;
     profileSnapshot: z.ZodOptional<z.ZodObject<{
         headline: z.ZodString;
@@ -152,3 +153,18 @@ export declare const AgentCardSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type AgentCard = z.infer<typeof AgentCardSchema>;
+/**
+ * Return the inbound message URL for an Agent Card.
+ *
+ * Under v0.1.1, `endpoint` is still required on every parsed
+ * `AgentCard`, so this helper effectively returns `card.endpoint`
+ * today. The `?? card.inboxEndpoint` fallback is in place for the
+ * future v0.x revision where `inboxEndpoint` will become primary
+ * (with `endpoint` accepted as the legacy alias). Consumers SHOULD
+ * use this helper rather than reading `.endpoint` directly so the
+ * eventual swap is a one-import change.
+ *
+ * `inboxEndpoint` (when present alongside `endpoint`) MUST equal
+ * `endpoint`; that invariant is enforced by `AgentCardSchema`.
+ */
+export declare function resolveAgentInbox(card: AgentCard): string;

package/dist/models/agent-card.js

@@ -17,8 +17,21 @@ export const AgentCardSchema = z.object({
     atprotoRecordUri: z.string().optional(),
     handle: z.string(),
     displayName: z.string().max(200),
+    /**
+     * Inbound message endpoint URL. Required.
+     *
+     * `inboxEndpoint` is accepted as an optional forward-compat hint
+     * from v0.1.1 onward; when present it MUST equal `endpoint`. The
+     * long-term name is settled at the next wire-version bump, so
+     * publishers SHOULD continue to emit `endpoint` for v0.1.x and
+     * MAY emit `inboxEndpoint` alongside it. The runtime helper
+     * `resolveAgentInbox(card)` returns whichever value is present.
+     */
     endpoint: z.string().url(),
+    inboxEndpoint: z.string().url().optional(),
     publicKeyMultibase: z.string().startsWith("z"),
+    // (other fields below; the `inboxEndpoint === endpoint` invariant
+    // is enforced by the .superRefine() at the bottom of this schema.)
     profileSnapshot: ProfileSnapshotSchema.optional(),
     capabilities: z.object({
         intentsAccepted: z.array(IntentTypeSchema),
@@ -56,4 +69,39 @@ export const AgentCardSchema = z.object({
             maxIntentsPerMinute: z.number().int().positive().optional(),
         }).optional(),
     }).optional(),
+}).superRefine((card, ctx) => {
+    // v0.1.1: when both endpoint and inboxEndpoint are present they
+    // MUST refer to the same URL. The spec rationale is that the alias
+    // exists for forward compat, not as a way to publish two distinct
+    // inbound URLs under one card — a card with mismatched endpoints
+    // is ambiguous about which one to deliver to.
+    if (card.inboxEndpoint && card.endpoint && card.inboxEndpoint !== card.endpoint) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["inboxEndpoint"],
+            message: "inboxEndpoint MUST equal endpoint when both are present (v0.1.1 spec).",
+        });
+    }
 });
+/**
+ * Return the inbound message URL for an Agent Card.
+ *
+ * Under v0.1.1, `endpoint` is still required on every parsed
+ * `AgentCard`, so this helper effectively returns `card.endpoint`
+ * today. The `?? card.inboxEndpoint` fallback is in place for the
+ * future v0.x revision where `inboxEndpoint` will become primary
+ * (with `endpoint` accepted as the legacy alias). Consumers SHOULD
+ * use this helper rather than reading `.endpoint` directly so the
+ * eventual swap is a one-import change.
+ *
+ * `inboxEndpoint` (when present alongside `endpoint`) MUST equal
+ * `endpoint`; that invariant is enforced by `AgentCardSchema`.
+ */
+export function resolveAgentInbox(card) {
+    // `card.endpoint` is required by the v0.1.x schema so the first
+    // branch always succeeds today. The `??` chain is in place for the
+    // future revision where `endpoint` becomes optional and
+    // `inboxEndpoint` becomes the primary field; consumers using this
+    // helper get the swap for free.
+    return card.endpoint ?? card.inboxEndpoint;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adastracomputing/ink",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.1",
   "description": "Library and specification for the INK (Inter-agent Networking Kernel) protocol",
   "license": "MIT OR Apache-2.0",
   "author": "Ad Astra Computing Inc.",

package/specs/ink-auditability.md

@@ -425,7 +425,7 @@ A third-party audit service is a **INK service role**, not a standard INK agent.
 | Concern | INK Agent | Audit Service |
 |---------|-----------|--------------|
 | Identity | DID bound to a human via `agentLink` | `did:web` or `did:key`, self-sovereign, no human owner |
-| Discovery | `TulpaAgentEndpoint` in DID document | Advertised in subscribing agents' Agent Card `capabilities.thirdPartyAudit.services` |
+| Discovery | `INKAgentEndpoint` in DID document (legacy `TulpaAgentEndpoint` also accepted during v0.1.x) | Advertised in subscribing agents' Agent Card `capabilities.thirdPartyAudit.services` |
 | Auth (inbound) | INK auth §3.3, verifies sender's `agentLink` delegation | INK auth §3.3, verifies sender's `agentLink` delegation (same as any INK endpoint) |
 | Auth (outbound) | Signs with `agentLink.signingKeyMultibase` | Signs with its own Ed25519 key (published in subscribing agents' Agent Card) |
 | Delegation proof | Required, must trace authority back to a human DID | Not applicable, the service is independently trusted by each subscribing agent |
@@ -436,7 +436,7 @@ A third-party audit service is a **INK service role**, not a standard INK agent.
 
 2. **Inbound auth is standard INK.** When agents submit events TO the service, the service verifies the submitter's identity via standard INK auth (§3.3), resolve the sender's DID, find their `agentLink`, verify the signature. The service is a normal INK recipient in this direction.
 
-3. **Service DID resolution.** The service's `did:web` (or `did:key`) is resolved normally for TLS binding and key discovery, but the service does NOT need a `TulpaAgentEndpoint` service entry in its DID document. Its endpoint is provided directly in the subscribing agent's Agent Card configuration.
+3. **Service DID resolution.** The service's `did:web` (or `did:key`) is resolved normally for TLS binding and key discovery, but the service does NOT need an `INKAgentEndpoint` service entry in its DID document. Its endpoint is provided directly in the subscribing agent's Agent Card configuration.
 
 4. **No inbox, no intents.** The audit service does not accept INK intents, challenges or resolutions. It exposes only the audit-specific endpoints (`/ink/v1/audit/submit`, `/ink/v1/audit/query`).
 

package/specs/ink-containment-phase1-implementation-spec.md

@@ -182,7 +182,7 @@ When visibility is `capability_gated`, unauthenticated requests to the Agent Car
 
 ```typescript
 interface RedactedAgentCard {
-  type: "tulpa.agent.card";
+  type: "ink.agent.card";  // legacy "tulpa.agent.card" MUST also be accepted during v0.1.x
   version: "1.0";
   agentId: string;
   displayName?: string;