@adastracomputing/ink 0.1.0-alpha.3 → 0.1.1

package/dist/middleware/ink-auth.d.ts

@@ -0,0 +1,68 @@
+import type { CandidateKey, KeyStatus } from "../models/key-entry.js";
+/**
+ * Pluggable nonce-record interface. The middleware uses this to enforce
+ * single-use semantics on body.nonce so a captured-and-replayed request
+ * is rejected even within the timestamp freshness window.
+ */
+export interface NonceStore {
+    has(nonce: string): boolean | Promise<boolean>;
+    add(nonce: string): void | Promise<void>;
+}
+/**
+ * Parse and verify an INK-Ed25519 Authorization header.
+ *
+ * The spec (§3.3) defines request signing as:
+ *   Authorization: INK-Ed25519 <base64url(sig)>
+ *
+ * Signature base: ink/0.1\nMETHOD\nPATH\nrecipientDid\nJCS(body)\ntimestamp
+ *
+ * The body must contain `from` (sender DID/agentId — used to resolve the public key)
+ * and `timestamp` (used in the signature base).
+ *
+ * Also enforces timestamp freshness per §3.5:
+ * - Rejects timestamps older than 5 minutes
+ * - Rejects timestamps more than 30 seconds in the future
+ *
+ * Key resolution order:
+ * 1. resolveKeySet (multi-key, if provided and returns candidates)
+ * 2. resolvePublicKey (single-key from connection store)
+ * 3. extractPublicKeyFromAgentId (bootstrap fallback — only when no key set exists)
+ */
+export declare function verifyInkAuth(opts: {
+    authHeader: string | undefined;
+    method: string;
+    path: string;
+    recipientAgentId: string;
+    body: Record<string, unknown>;
+    resolvePublicKey?: (agentId: string) => Uint8Array | null;
+    resolveKeySet?: (agentId: string) => CandidateKey[] | null;
+    /**
+     * When true, signatures that only verify against a retired key are
+     * rejected with `retired_key_for_live_auth`. Defaults to false so the
+     * middleware stays spec-conformant (active OR retired during rotation
+     * grace per the authority rule) but lets callers opt into the stricter
+     * policy for endpoints that should never accept a possibly-stolen
+     * retired key. Bootstrap and single-key (resolvePublicKey) verification
+     * paths are unaffected because they do not have status metadata.
+     */
+    requireActiveKey?: boolean;
+    /**
+     * Single-use nonce enforcement. Required (fail-closed) because the
+     * 5-minute freshness window otherwise allows a captured signed request
+     * to replay. Pass a NonceStore to have the middleware check+record
+     * body.nonce, or pass the literal "deferred" to explicitly take
+     * responsibility for calling `checkReplay` (or equivalent) in the
+     * caller's own request pipeline. Omitting this option returns
+     * `nonce_handling_required` so misconfigured production deployments
+     * fail loudly.
+     */
+    nonceStore: NonceStore | "deferred";
+}): Promise<{
+    valid: true;
+    senderAgentId: string;
+    keyId?: string;
+    keyStatus?: KeyStatus;
+} | {
+    valid: false;
+    error: string;
+}>;

package/dist/middleware/ink-auth.js

@@ -0,0 +1,214 @@
+import { verifyInkSignature, MAX_TIMESTAMP_AGE_MS, MAX_FUTURE_TIMESTAMP_MS } from "../crypto/ink.js";
+import { extractPublicKeyFromAgentId } from "../crypto/keys.js";
+import { verifyInkSignatureWithKeys } from "../crypto/multi-key-verify.js";
+/**
+ * Parse and verify an INK-Ed25519 Authorization header.
+ *
+ * The spec (§3.3) defines request signing as:
+ *   Authorization: INK-Ed25519 <base64url(sig)>
+ *
+ * Signature base: ink/0.1\nMETHOD\nPATH\nrecipientDid\nJCS(body)\ntimestamp
+ *
+ * The body must contain `from` (sender DID/agentId — used to resolve the public key)
+ * and `timestamp` (used in the signature base).
+ *
+ * Also enforces timestamp freshness per §3.5:
+ * - Rejects timestamps older than 5 minutes
+ * - Rejects timestamps more than 30 seconds in the future
+ *
+ * Key resolution order:
+ * 1. resolveKeySet (multi-key, if provided and returns candidates)
+ * 2. resolvePublicKey (single-key from connection store)
+ * 3. extractPublicKeyFromAgentId (bootstrap fallback — only when no key set exists)
+ */
+export async function verifyInkAuth(opts) {
+    if (typeof opts.authHeader !== "string" || opts.authHeader.length === 0) {
+        return { valid: false, error: "missing_authorization" };
+    }
+    if (opts.body === null || typeof opts.body !== "object" || Array.isArray(opts.body)) {
+        return { valid: false, error: "missing_sender" };
+    }
+    if (opts.authHeader.length > 512) {
+        return { valid: false, error: "invalid_auth_scheme" };
+    }
+    // Ed25519 signatures are exactly 86 base64url chars — tighten the regex to
+    // {86} so clearly-wrong lengths get rejected up front, rather than burning
+    // CPU on verifyInkSignature for a malformed value.
+    const match = opts.authHeader.match(/^INK-Ed25519\s+([A-Za-z0-9_-]{86})(?:\s+keyId=([A-Za-z0-9_:.-]{1,128}))?$/);
+    if (!match) {
+        return { valid: false, error: "invalid_auth_scheme" };
+    }
+    const signature = match[1];
+    const hintKeyId = match[2] ?? undefined;
+    const senderDid = opts.body.from;
+    if (senderDid !== undefined && typeof senderDid !== "string") {
+        return { valid: false, error: "invalid_from_field" };
+    }
+    if (!senderDid) {
+        return { valid: false, error: "missing_sender" };
+    }
+    // Cap sender DID length before passing to key resolvers and base58 decoding.
+    // Real agent IDs are ~50-100 chars; 256 leaves generous headroom while
+    // preventing CPU/memory waste on huge attacker-supplied values.
+    if (senderDid.length > 256) {
+        return { valid: false, error: "invalid_from_field" };
+    }
+    const timestamp = opts.body.timestamp;
+    if (typeof timestamp !== "string" || timestamp.length === 0) {
+        return { valid: false, error: "missing_timestamp" };
+    }
+    // Cap length BEFORE handing to Date.parse. Real ISO 8601 timestamps
+    // are ≤ ~30 chars; we cap at 64 (matches buildSignatureBase). Without
+    // this, an unauthenticated request with a multi-megabyte timestamp
+    // string burns CPU inside the engine's Date parser before the
+    // signature ever runs.
+    if (timestamp.length > 64) {
+        return { valid: false, error: "invalid_timestamp" };
+    }
+    // Timestamp freshness check (§3.5)
+    const msgTime = new Date(timestamp).getTime();
+    if (isNaN(msgTime)) {
+        return { valid: false, error: "invalid_timestamp" };
+    }
+    const now = Date.now();
+    const drift = msgTime - now;
+    if (drift > MAX_FUTURE_TIMESTAMP_MS) {
+        return { valid: false, error: "timestamp_too_far_future" };
+    }
+    if (-drift > MAX_TIMESTAMP_AGE_MS) {
+        return { valid: false, error: "timestamp_expired" };
+    }
+    // Fail-closed nonce policy. Callers must either pass a NonceStore
+    // (middleware enforces single-use within the freshness window) or
+    // explicitly pass "deferred" (caller commits to calling checkReplay
+    // or equivalent in their request pipeline). An omitted/malformed
+    // nonceStore returns nonce_handling_required so a production
+    // deployment without nonce handling fails loudly rather than
+    // silently accepting replays.
+    const storeIsObject = opts.nonceStore !== "deferred" &&
+        opts.nonceStore !== undefined &&
+        opts.nonceStore !== null &&
+        typeof opts.nonceStore.has === "function" &&
+        typeof opts.nonceStore.add === "function";
+    if (opts.nonceStore !== "deferred" && !storeIsObject) {
+        return { valid: false, error: "nonce_handling_required" };
+    }
+    const usingNonceStore = storeIsObject;
+    let bodyNonce;
+    if (usingNonceStore) {
+        const candidate = opts.body.nonce;
+        if (typeof candidate !== "string" ||
+            candidate.length < 16 ||
+            candidate.length > 256 ||
+            !/^[A-Za-z0-9_-]+$/.test(candidate)) {
+            return { valid: false, error: "missing_nonce" };
+        }
+        bodyNonce = candidate;
+    }
+    const input = {
+        method: opts.method,
+        path: opts.path,
+        recipientDid: opts.recipientAgentId,
+        body: opts.body,
+        timestamp,
+    };
+    // Post-verify nonce check+record. Runs only when the caller provided
+    // a NonceStore object. Checking after signature verification means a
+    // forged request never pollutes the nonce store, but a replay of an
+    // authentic signed request is still rejected within the freshness
+    // window. Backend errors fail closed.
+    async function recordNonce() {
+        if (!usingNonceStore)
+            return { ok: true };
+        const store = opts.nonceStore;
+        const nonce = bodyNonce;
+        let alreadySeen;
+        try {
+            alreadySeen = await Promise.resolve(store.has(nonce));
+        }
+        catch {
+            return { ok: false, error: "nonce_store_error" };
+        }
+        if (alreadySeen)
+            return { ok: false, error: "nonce_replay" };
+        try {
+            await Promise.resolve(store.add(nonce));
+        }
+        catch {
+            return { ok: false, error: "nonce_store_error" };
+        }
+        return { ok: true };
+    }
+    // Try multi-key verification first (Phase 1 key rotation support).
+    // If the agent has published a key set, it is authoritative: we must NOT
+    // fall through to resolvePublicKey or the bootstrap derivation, because
+    // either could surface a key (retired/revoked or stale conn-stored) that
+    // was already rejected — or deliberately excluded — from the key set.
+    if (opts.resolveKeySet) {
+        const candidates = opts.resolveKeySet(senderDid);
+        // null/undefined = no key set published for this agent → fall through to bootstrap.
+        // Empty array = key set exists but no usable signing keys (e.g. all revoked) →
+        // authoritative reject. Falling through here would let an attacker with the
+        // bootstrap-derived key authenticate even after the agent has revoked it.
+        if (candidates !== null && candidates !== undefined) {
+            if (candidates.length === 0) {
+                return { valid: false, error: "signature_verification_failed" };
+            }
+            try {
+                const result = await verifyInkSignatureWithKeys(input, signature, candidates, hintKeyId);
+                if (result.verified) {
+                    // Local-policy gate: a retired key still verifies per the spec's
+                    // authority rule, but a caller that runs sensitive endpoints
+                    // (writes, capability grants, etc.) can require an active key.
+                    // This closes the "stolen retired key signs a fresh message"
+                    // window: even though the spec allows retired keys for grace,
+                    // callers don't have to.
+                    if (opts.requireActiveKey && result.keyStatus === "retired") {
+                        return { valid: false, error: "retired_key_for_live_auth" };
+                    }
+                    const noncePass = await recordNonce();
+                    if (!noncePass.ok)
+                        return { valid: false, error: noncePass.error };
+                    return {
+                        valid: true,
+                        senderAgentId: senderDid,
+                        keyId: result.keyId,
+                        keyStatus: result.keyStatus,
+                    };
+                }
+            }
+            catch { /* treated as verification failure below */ }
+            // Authoritative key set rejected the signature — do not fall back.
+            return { valid: false, error: "signature_verification_failed" };
+        }
+    }
+    // No key set published yet — first-contact / bootstrap path.
+    let publicKey = null;
+    if (opts.resolvePublicKey) {
+        publicKey = opts.resolvePublicKey(senderDid);
+    }
+    if (!publicKey) {
+        try {
+            publicKey = extractPublicKeyFromAgentId(senderDid);
+        }
+        catch {
+            return { valid: false, error: "unresolvable_sender_key" };
+        }
+    }
+    if (!publicKey) {
+        return { valid: false, error: "unresolvable_sender_key" };
+    }
+    try {
+        const valid = await verifyInkSignature(input, signature, publicKey);
+        if (!valid) {
+            return { valid: false, error: "invalid_signature" };
+        }
+        const noncePass = await recordNonce();
+        if (!noncePass.ok)
+            return { valid: false, error: noncePass.error };
+        return { valid: true, senderAgentId: senderDid };
+    }
+    catch {
+        return { valid: false, error: "signature_verification_failed" };
+    }
+}

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

@@ -0,0 +1,170 @@
+import { z } from "zod";
+export declare const ThirdPartyAuditServiceSchema: z.ZodObject<{
+    endpoint: z.ZodString;
+    did: z.ZodString;
+    publicKey: z.ZodString;
+}, z.core.$strip>;
+export declare const AgentCardSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"ink/0.1">;
+    agentId: z.ZodString;
+    ownerDid: z.ZodOptional<z.ZodString>;
+    ownerHandle: z.ZodOptional<z.ZodString>;
+    atprotoRecordUri: z.ZodOptional<z.ZodString>;
+    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;
+        skills: z.ZodArray<z.ZodString>;
+        interests: z.ZodArray<z.ZodString>;
+        availability: z.ZodOptional<z.ZodObject<{
+            timezone: z.ZodString;
+            meetingHours: z.ZodOptional<z.ZodString>;
+            responseSla: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        openTo: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    capabilities: z.ZodObject<{
+        intentsAccepted: z.ZodArray<z.ZodEnum<{
+            schedule_meeting: "schedule_meeting";
+            schedule_meeting_response: "schedule_meeting_response";
+            intro_request: "intro_request";
+            intro_response: "intro_response";
+            opportunity: "opportunity";
+            opportunity_response: "opportunity_response";
+            follow_up: "follow_up";
+            ask: "ask";
+            ask_response: "ask_response";
+            connection_request: "connection_request";
+            connection_response: "connection_response";
+            context_share: "context_share";
+            ping: "ping";
+            retract: "retract";
+            multi_party_sync: "multi_party_sync";
+        }>>;
+        intentsSent: z.ZodArray<z.ZodEnum<{
+            schedule_meeting: "schedule_meeting";
+            schedule_meeting_response: "schedule_meeting_response";
+            intro_request: "intro_request";
+            intro_response: "intro_response";
+            opportunity: "opportunity";
+            opportunity_response: "opportunity_response";
+            follow_up: "follow_up";
+            ask: "ask";
+            ask_response: "ask_response";
+            connection_request: "connection_request";
+            connection_response: "connection_response";
+            context_share: "context_share";
+            ping: "ping";
+            retract: "retract";
+            multi_party_sync: "multi_party_sync";
+        }>>;
+        receipts: z.ZodOptional<z.ZodObject<{
+            send: z.ZodBoolean;
+            dispositions: z.ZodArray<z.ZodEnum<{
+                received: "received";
+                delivered: "delivered";
+                acted: "acted";
+                rejected: "rejected";
+                expired: "expired";
+            }>>;
+        }, z.core.$strip>>;
+        auditExchange: z.ZodOptional<z.ZodBoolean>;
+        thirdPartyAudit: z.ZodOptional<z.ZodObject<{
+            services: z.ZodArray<z.ZodObject<{
+                endpoint: z.ZodString;
+                did: z.ZodString;
+                publicKey: z.ZodString;
+            }, z.core.$strip>>;
+            submitPolicy: z.ZodEnum<{
+                none: "none";
+                all: "all";
+                high_value: "high_value";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    availability: z.ZodObject<{
+        timezone: z.ZodString;
+        meetingHours: z.ZodOptional<z.ZodString>;
+        responseSla: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    keys: z.ZodOptional<z.ZodObject<{
+        signing: z.ZodArray<z.ZodObject<{
+            keyId: z.ZodString;
+            algorithm: z.ZodEnum<{
+                Ed25519: "Ed25519";
+                X25519: "X25519";
+            }>;
+            publicKeyMultibase: z.ZodString;
+            status: z.ZodEnum<{
+                active: "active";
+                retired: "retired";
+                revoked: "revoked";
+            }>;
+            validFrom: z.ZodString;
+            validUntil: z.ZodOptional<z.ZodString>;
+            revokedAt: z.ZodOptional<z.ZodString>;
+            revokeReason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        encryption: z.ZodArray<z.ZodObject<{
+            keyId: z.ZodString;
+            algorithm: z.ZodEnum<{
+                Ed25519: "Ed25519";
+                X25519: "X25519";
+            }>;
+            publicKeyMultibase: z.ZodString;
+            status: z.ZodEnum<{
+                active: "active";
+                retired: "retired";
+                revoked: "revoked";
+            }>;
+            validFrom: z.ZodString;
+            validUntil: z.ZodOptional<z.ZodString>;
+            revokedAt: z.ZodOptional<z.ZodString>;
+            revokeReason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    currentSigningKeyId: z.ZodOptional<z.ZodString>;
+    currentEncryptionKeyId: z.ZodOptional<z.ZodString>;
+    keySetVersion: z.ZodOptional<z.ZodNumber>;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        network_only: "network_only";
+        capability_gated: "capability_gated";
+        private: "private";
+    }>>;
+    governance: z.ZodOptional<z.ZodObject<{
+        maxAcceptedDelegationDepth: z.ZodOptional<z.ZodNumber>;
+        supportedTransports: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            ink_http: "ink_http";
+            ink_ws: "ink_ws";
+            extension_api: "extension_api";
+            voice: "voice";
+            line_phone: "line_phone";
+            human_review_queue: "human_review_queue";
+        }>>>;
+        supportsCapabilityGatedDiscovery: z.ZodOptional<z.ZodBoolean>;
+        handshakeBudget: z.ZodOptional<z.ZodObject<{
+            maxChallengesPerCorrelation: z.ZodOptional<z.ZodNumber>;
+            maxIntentsPerMinute: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, 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

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { IntentTypeSchema } from "./intent.js";
+import { InkReceiptDispositionSchema } from "./ink-audit.js";
+import { ProfileSnapshotSchema } from "./profile.js";
+import { KeyEntrySchema } from "./key-entry.js";
+import { InkTransportSchema, AgentCardVisibilitySchema } from "./ink-handshake.js";
+export const ThirdPartyAuditServiceSchema = z.object({
+    endpoint: z.string().url(),
+    did: z.string(),
+    publicKey: z.string(),
+});
+export const AgentCardSchema = z.object({
+    protocol: z.literal("ink/0.1"),
+    agentId: z.string(),
+    ownerDid: z.string().optional(),
+    ownerHandle: z.string().optional(),
+    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),
+        intentsSent: z.array(IntentTypeSchema),
+        receipts: z.object({
+            send: z.boolean(),
+            dispositions: z.array(InkReceiptDispositionSchema),
+        }).optional(),
+        auditExchange: z.boolean().optional(),
+        thirdPartyAudit: z.object({
+            services: z.array(ThirdPartyAuditServiceSchema),
+            submitPolicy: z.enum(["all", "high_value", "none"]),
+        }).optional(),
+    }),
+    availability: z.object({
+        timezone: z.string(),
+        meetingHours: z.string().optional(),
+        responseSla: z.string().optional(),
+    }),
+    keys: z.object({
+        signing: z.array(KeyEntrySchema),
+        encryption: z.array(KeyEntrySchema),
+    }).optional(),
+    currentSigningKeyId: z.string().optional(),
+    currentEncryptionKeyId: z.string().optional(),
+    keySetVersion: z.number().int().positive().optional(),
+    // Containment extension (Phase 1)
+    visibility: AgentCardVisibilitySchema.optional(),
+    governance: z.object({
+        maxAcceptedDelegationDepth: z.number().int().positive().optional(),
+        supportedTransports: z.array(InkTransportSchema).optional(),
+        supportsCapabilityGatedDiscovery: z.boolean().optional(),
+        handshakeBudget: z.object({
+            maxChallengesPerCorrelation: z.number().int().positive().optional(),
+            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;
+}