@adastracomputing/ink 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/ink/handshake-budget.js

@@ -0,0 +1,397 @@
+/**
+ * Handshake flood resistance — per-correlation and per-sender budget tracking.
+ *
+ * Implements §5 of the INK Containment spec:
+ * - Per-correlation budgets: max challenges, terminal states, total transitions, TTL
+ * - Per-sender rate limits: sliding window for intents and total handshake messages
+ * - First violation returns typed rejection with backoff hint
+ * - Subsequent violations are silent drops
+ */
+// ── Budget constants ──
+const DEFAULT_MAX_CHALLENGES = 3;
+const DEFAULT_MAX_TOTAL_TRANSITIONS = 5;
+const DEFAULT_MAX_INTENTS_PER_MINUTE = 10;
+const DEFAULT_MAX_HANDSHAKE_MSGS_PER_MINUTE = 30;
+const DEFAULT_MAX_CORRELATIONS = 10_000;
+const DEFAULT_MAX_SENDERS = 1_000;
+const DEFAULT_MAX_REJECTION_ENTRIES = 5_000;
+const DEFAULT_PRUNE_INTERVAL = 100;
+const DEFAULT_HANDSHAKE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+// Cap correlationId and fromDid lengths to prevent memory exhaustion via large IDs.
+// Real correlation IDs are UUIDs (~36 chars); agent DIDs are ~50-100 chars.
+// 256 is generous headroom while bounding per-entry memory cost.
+const MAX_ID_LENGTH = 256;
+const SENDER_REJECTION_WINDOW_MS = 60_000;
+const TERMINAL_TYPES = new Set(["rejection", "resolution"]);
+// ── Budget tracker ──
+export class HandshakeBudgetTracker {
+    correlations = new Map();
+    senders = new Map();
+    rejectionsSent = new Set(); // "${correlationId}:${fromDid}"
+    // Tracks when a sender last received a rate-limit rejection. Subsequent
+    // violations within SENDER_REJECTION_WINDOW_MS are silent-dropped to prevent
+    // an over-limit sender from forcing repeated reject/backoff responses.
+    senderRejectionsSent = new Map();
+    maxChallenges;
+    maxTotalTransitions;
+    maxIntentsPerMinute;
+    maxHandshakeMsgsPerMinute;
+    maxCorrelations;
+    maxSenders;
+    maxRejectionEntries;
+    checkCounter = 0;
+    constructor(config = {}) {
+        const pos = (v, def, cap) => {
+            if (typeof v !== "number" || !Number.isFinite(v) || v <= 0)
+                return def;
+            return Math.min(Math.floor(v), cap);
+        };
+        this.maxChallenges = pos(config.maxChallenges, DEFAULT_MAX_CHALLENGES, 1_000);
+        this.maxTotalTransitions = pos(config.maxTotalTransitions, DEFAULT_MAX_TOTAL_TRANSITIONS, 10_000);
+        this.maxIntentsPerMinute = pos(config.maxIntentsPerMinute, DEFAULT_MAX_INTENTS_PER_MINUTE, 100_000);
+        this.maxHandshakeMsgsPerMinute = pos(config.maxHandshakeMsgsPerMinute, DEFAULT_MAX_HANDSHAKE_MSGS_PER_MINUTE, 100_000);
+        this.maxCorrelations = pos(config.maxCorrelations, DEFAULT_MAX_CORRELATIONS, 1_000_000);
+        this.maxSenders = pos(config.maxSenders, DEFAULT_MAX_SENDERS, 1_000_000);
+        this.maxRejectionEntries = pos(config.maxRejectionEntries, DEFAULT_MAX_REJECTION_ENTRIES, 1_000_000);
+    }
+    /**
+     * Side-effect-free budget check. Returns the same BudgetCheckResult as
+     * checkAndRecord without mutating any internal state: no sender activity
+     * recorded, no correlation row created for an unknown intentRef, no
+     * transition counter incremented, no terminal flag set, and no rejection
+     * bookkeeping (rejectionsSent / senderRejectionsSent) advanced. Use this
+     * when you want to gate on budget BEFORE running expensive validation
+     * (signature verification, state-machine), then call recordAccepted()
+     * only on acceptance.
+     *
+     * Without the split, an invalid signed envelope for a known intentRef
+     * could pass the budget check, mark the correlation as terminal, then
+     * fail downstream validation — blocking later legitimate traffic for
+     * that correlation. Integrators that want the original eager-commit
+     * semantics can keep calling checkAndRecord.
+     */
+    check(params) {
+        return this.checkOrRecord(params, /* commit */ false);
+    }
+    /**
+     * Commit a previously-checked acceptance. The check() return value is
+     * not load-bearing here — this method runs the same checks again and
+     * applies the mutation. Callers are responsible for not re-running
+     * recordAccepted() on the same message; a nonce cache typically
+     * prevents that path.
+     */
+    recordAccepted(params) {
+        return this.checkOrRecord(params, /* commit */ true);
+    }
+    checkAndRecord(params) {
+        return this.checkOrRecord(params, /* commit */ true);
+    }
+    checkOrRecord(params, commit) {
+        const { correlationId, fromDid, messageType, intentExpiresAt } = params;
+        const now = Date.now();
+        // Reject unbounded IDs before they hit Map keys / Set entries — caps the
+        // per-entry memory cost regardless of the maxCorrelations / maxSenders
+        // count caps. Stringifying the whole pair amplifies the attack surface.
+        if (typeof correlationId !== "string" || correlationId.length > MAX_ID_LENGTH ||
+            typeof fromDid !== "string" || fromDid.length > MAX_ID_LENGTH) {
+            return { allowed: false, reason: "handshake_budget_exhausted", silentDrop: true };
+        }
+        // Use JSON encoding to prevent key collisions when IDs contain colons.
+        // e.g. correlationId="a:b", fromDid="c" vs correlationId="a", fromDid="b:c"
+        // would both produce "a:b:c" with naive string concatenation.
+        const pairKey = JSON.stringify([correlationId, fromDid]);
+        // Periodic pruning of expired state
+        this.checkCounter++;
+        if (this.checkCounter >= DEFAULT_PRUNE_INTERVAL) {
+            this.checkCounter = 0;
+            this.pruneExpired();
+        }
+        // Check per-sender rate limits first (applies across all correlations)
+        const senderResult = this.checkSenderLimits(fromDid, messageType, now, commit);
+        if (!senderResult.allowed) {
+            return senderResult;
+        }
+        // Record sender activity FIRST so per-sender limits accumulate on every
+        // syntactically valid attempt — including ones that fail downstream
+        // budget checks. Otherwise an attacker varying correlationId can trigger
+        // unlimited typed rejections without ever hitting the per-sender cap.
+        // Skip in check-only mode so the public check() is side-effect free.
+        if (commit) {
+            this.recordSenderActivity(fromDid, messageType, now);
+        }
+        // Check TTL from intent expiry.
+        // Distinguish "field absent" (undefined) from "field present but
+        // malformed/empty". An intent that supplies `intentExpiresAt: ""`
+        // is malformed — treat it as a rejected handshake instead of
+        // falling through to the default 24h TTL (which would let
+        // attacker-supplied empty expiries retain state longer than the
+        // sender's claimed window). Also guard against NaN: new
+        // Date("garbage").getTime() returns NaN and NaN <= now is false.
+        let parsedExpiryMs = null;
+        if (intentExpiresAt !== undefined) {
+            // Length cap matches the timestamp cap used everywhere else in
+            // INK (64 chars, well above any real ISO 8601 string). Without
+            // this, a sender can submit a multi-megabyte expiry string and
+            // force the JS engine into a long Date parser run before the
+            // budget tracker rejects.
+            if (typeof intentExpiresAt !== "string" ||
+                intentExpiresAt.length === 0 ||
+                intentExpiresAt.length > 64) {
+                return this.makeRejection(pairKey, "handshake_budget_exhausted", {
+                    backoffClass: "intent_ref",
+                }, commit);
+            }
+            const expiryMs = new Date(intentExpiresAt).getTime();
+            if (!Number.isFinite(expiryMs) || expiryMs <= now) {
+                return this.makeRejection(pairKey, "handshake_budget_exhausted", {
+                    backoffClass: "intent_ref",
+                }, commit);
+            }
+            parsedExpiryMs = expiryMs;
+        }
+        // Get or create correlation state. KEY BY pairKey, not correlationId,
+        // so two senders that happen to use the same correlationId can't
+        // consume each other's transitions or set terminal state on each
+        // other's handshake.
+        let state = this.correlations.get(pairKey);
+        if (!state) {
+            if (!commit) {
+                // Check-only mode does NOT create a row for an unknown
+                // correlation — that would itself be a side effect and would
+                // let unauthenticated traffic balloon the in-memory map.
+                return { allowed: true };
+            }
+            // Enforce memory bounds before creating new entry
+            this.enforceMemoryBounds();
+            // Reuse the parsed expiry from above instead of re-parsing.
+            const ttl = parsedExpiryMs !== null
+                ? Math.min(parsedExpiryMs, now + DEFAULT_HANDSHAKE_TTL_MS)
+                : now + DEFAULT_HANDSHAKE_TTL_MS;
+            state = {
+                challenges: 0,
+                totalTransitions: 0,
+                terminal: false,
+                expiresAt: ttl,
+                createdAt: now,
+            };
+            this.correlations.set(pairKey, state);
+        }
+        // Check if correlation has expired
+        if (state.expiresAt <= now) {
+            return this.makeRejection(pairKey, "handshake_budget_exhausted", {
+                backoffClass: "intent_ref",
+            }, commit);
+        }
+        // Check if terminal state was already reached
+        if (state.terminal) {
+            return this.makeRejection(pairKey, "handshake_budget_exhausted", {
+                backoffClass: "intent_ref",
+            }, commit);
+        }
+        // Check total transitions
+        if (state.totalTransitions >= this.maxTotalTransitions) {
+            return this.makeRejection(pairKey, "handshake_budget_exhausted", {
+                backoffClass: "intent_ref",
+            }, commit);
+        }
+        // Check per-type limits
+        if (messageType === "challenge" && state.challenges >= this.maxChallenges) {
+            return this.makeRejection(pairKey, "handshake_budget_exhausted", {
+                backoffClass: "intent_ref",
+            }, commit);
+        }
+        if (!commit) {
+            return { allowed: true };
+        }
+        // Record the message
+        state.totalTransitions++;
+        if (messageType === "challenge") {
+            state.challenges++;
+        }
+        if (TERMINAL_TYPES.has(messageType)) {
+            state.terminal = true;
+        }
+        // Sender activity was already recorded above (before the budget checks)
+        // so per-sender limits accumulate even on rejected attempts.
+        return { allowed: true };
+    }
+    pruneExpired() {
+        const now = Date.now();
+        for (const [pairKey, state] of this.correlations) {
+            if (state.expiresAt <= now) {
+                this.correlations.delete(pairKey);
+                // Rejection tracking is keyed by the same pairKey, so we can drop
+                // it directly.
+                this.rejectionsSent.delete(pairKey);
+            }
+        }
+        // Prune stale sender windows
+        const oneMinuteAgo = now - 60_000;
+        for (const [did, state] of this.senders) {
+            state.intentTimestamps = state.intentTimestamps.filter((t) => t > oneMinuteAgo);
+            state.handshakeTimestamps = state.handshakeTimestamps.filter((t) => t > oneMinuteAgo);
+            if (state.intentTimestamps.length === 0 && state.handshakeTimestamps.length === 0) {
+                this.senders.delete(did);
+            }
+        }
+        // Prune sender-rejection records older than the silent-drop window.
+        for (const [did, ts] of this.senderRejectionsSent) {
+            if (now - ts >= SENDER_REJECTION_WINDOW_MS) {
+                this.senderRejectionsSent.delete(did);
+            }
+        }
+    }
+    checkSenderLimits(fromDid, messageType, now, commit) {
+        const state = this.senders.get(fromDid);
+        if (!state)
+            return { allowed: true };
+        const oneMinuteAgo = now - 60_000;
+        // Check per-minute intent limit
+        if (messageType === "intent") {
+            const recentIntents = state.intentTimestamps.filter((t) => t > oneMinuteAgo);
+            if (recentIntents.length >= this.maxIntentsPerMinute) {
+                return this.makeSenderRejection(fromDid, now, commit);
+            }
+        }
+        // Check per-minute total handshake message limit
+        const recentHandshake = state.handshakeTimestamps.filter((t) => t > oneMinuteAgo);
+        if (recentHandshake.length >= this.maxHandshakeMsgsPerMinute) {
+            return this.makeSenderRejection(fromDid, now, commit);
+        }
+        return { allowed: true };
+    }
+    // Sender-level rate-limit rejection. Sends a typed reject (with backoff hint)
+    // the first time a sender crosses the limit in the current window; silent-drops
+    // subsequent violations until the window resets. Mirrors the per-correlation
+    // makeRejection pattern from §5 of the INK Containment spec.
+    //
+    // When commit=false the rejection shape is computed without touching
+    // senderRejectionsSent, so check() can peek at the rate-limit state
+    // without burning the "typed rejection" budget for that sender.
+    makeSenderRejection(fromDid, now, commit) {
+        const lastSent = this.senderRejectionsSent.get(fromDid);
+        if (lastSent !== undefined && now - lastSent < SENDER_REJECTION_WINDOW_MS) {
+            return { allowed: false, reason: "sender_rate_limited", silentDrop: true };
+        }
+        if (!commit) {
+            // Observation-only: would have been a typed rejection on a commit
+            // path, but the silent-drop state machine is not advanced here.
+            return {
+                allowed: false,
+                reason: "sender_rate_limited",
+                backoffHint: { retryAfterSeconds: 60, backoffClass: "sender" },
+                silentDrop: false,
+            };
+        }
+        // Bound the map by maxSenders to prevent attacker-driven growth. Evict the
+        // oldest record if at capacity; the pruneExpired pass also cleans up
+        // records older than the silent-drop window.
+        if (this.senderRejectionsSent.size >= this.maxSenders &&
+            !this.senderRejectionsSent.has(fromDid)) {
+            let oldestDid = null;
+            let oldestTs = Infinity;
+            for (const [d, t] of this.senderRejectionsSent) {
+                if (t < oldestTs) {
+                    oldestTs = t;
+                    oldestDid = d;
+                }
+            }
+            if (oldestDid)
+                this.senderRejectionsSent.delete(oldestDid);
+        }
+        this.senderRejectionsSent.set(fromDid, now);
+        return {
+            allowed: false,
+            reason: "sender_rate_limited",
+            backoffHint: { retryAfterSeconds: 60, backoffClass: "sender" },
+            silentDrop: false,
+        };
+    }
+    recordSenderActivity(fromDid, messageType, now) {
+        let state = this.senders.get(fromDid);
+        if (!state) {
+            // Enforce sender cap before adding a new entry
+            this.enforceSenderBounds();
+            state = { intentTimestamps: [], handshakeTimestamps: [], lastActivity: now };
+            this.senders.set(fromDid, state);
+        }
+        state.lastActivity = now;
+        if (messageType === "intent") {
+            state.intentTimestamps.push(now);
+        }
+        state.handshakeTimestamps.push(now);
+    }
+    makeRejection(pairKey, reason, backoffHint, commit) {
+        if (this.rejectionsSent.has(pairKey)) {
+            return { allowed: false, reason, silentDrop: true };
+        }
+        if (!commit) {
+            // Observation-only: would have been the typed first-rejection on a
+            // commit path. rejectionsSent is left alone so that a subsequent
+            // recordAccepted (or checkAndRecord) for the same pairKey still
+            // gets the "first typed" response — otherwise check() would burn
+            // the typed-rejection budget for any pairKey it ever probed.
+            return { allowed: false, reason, backoffHint, silentDrop: false };
+        }
+        this.rejectionsSent.add(pairKey);
+        this.enforceRejectionBounds();
+        return { allowed: false, reason, backoffHint, silentDrop: false };
+    }
+    enforceRejectionBounds() {
+        if (this.rejectionsSent.size <= this.maxRejectionEntries)
+            return;
+        // Prune rejection entries whose backing correlation no longer exists
+        // (already expired or evicted). Rejection keys and correlation keys are
+        // both pairKeys now, so the lookup is direct.
+        const now = Date.now();
+        for (const key of this.rejectionsSent) {
+            const state = this.correlations.get(key);
+            if (!state || state.expiresAt <= now) {
+                this.rejectionsSent.delete(key);
+            }
+        }
+        // If still over limit, clear the oldest half (Set maintains insertion order)
+        if (this.rejectionsSent.size > this.maxRejectionEntries) {
+            const entries = [...this.rejectionsSent];
+            const keepFrom = Math.floor(entries.length / 2);
+            this.rejectionsSent.clear();
+            for (let i = keepFrom; i < entries.length; i++) {
+                this.rejectionsSent.add(entries[i]);
+            }
+        }
+    }
+    enforceSenderBounds() {
+        if (this.senders.size < this.maxSenders)
+            return;
+        // Evict sender with oldest lastActivity
+        let oldestDid = null;
+        let oldestTime = Infinity;
+        for (const [did, state] of this.senders) {
+            if (state.lastActivity < oldestTime) {
+                oldestTime = state.lastActivity;
+                oldestDid = did;
+            }
+        }
+        if (oldestDid) {
+            this.senders.delete(oldestDid);
+        }
+    }
+    enforceMemoryBounds() {
+        if (this.correlations.size < this.maxCorrelations)
+            return;
+        // Evict oldest entry (by createdAt)
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, state] of this.correlations) {
+            if (state.createdAt < oldestTime) {
+                oldestTime = state.createdAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.correlations.delete(oldestKey);
+            // Rejection tracking is keyed by the same pairKey, so drop directly.
+            this.rejectionsSent.delete(oldestKey);
+        }
+    }
+}

package/dist/ink/receipts.d.ts

@@ -0,0 +1,31 @@
+import type { InkReceipt } from "../models/ink-audit.js";
+export interface BuildReceiptInput {
+    from: string;
+    to: string;
+    messageId: string;
+    messageBody: Record<string, unknown>;
+    disposition: "received" | "delivered" | "acted" | "rejected";
+    note?: string;
+    privateKey: Uint8Array;
+}
+/** Build a signed INK receipt envelope. */
+export declare function buildReceipt(input: BuildReceiptInput): Promise<InkReceipt>;
+export declare function shouldSendReceipt(intentOrType: string): boolean;
+export interface SendReceiptOptions {
+    /** Allow endpoints whose hostname is loopback / private / link-local /
+     *  IANA special-use. Off by default — flip on only for tests or for
+     *  intentional intranet deployments where peer endpoints are trusted. */
+    allowPrivateHosts?: boolean;
+}
+/** Fire-and-forget POST of a receipt with INK request signature. Never throws.
+ *
+ *  Endpoint MUST be an absolute `https://` URL. Other schemes (file://, data:,
+ *  blob:, http://) are rejected silently to prevent SSRF and local-file
+ *  exfiltration when integrators pass peer-supplied URLs without sanitising.
+ *
+ *  Mirrors the SSRF defenses in fetchAgentCard: https-only, no userinfo,
+ *  literal-hostname allowlist excluding private/loopback/special-use, no
+ *  redirect following, request timeout. DNS rebinding is still the
+ *  integrator's responsibility — pass a connect-time-pinning `fetchFn`
+ *  when the endpoint is not fully trusted. */
+export declare function sendReceiptFireAndForget(endpoint: string, receipt: InkReceipt, privateKey: Uint8Array, fetchFn?: typeof fetch, signingKeyId?: string, options?: SendReceiptOptions): Promise<void>;

package/dist/ink/receipts.js

@@ -0,0 +1,89 @@
+import { computeMessageHash, signInkMessage, buildAuthHeader } from "../crypto/ink.js";
+import { signMessage } from "../crypto/sign.js";
+import { isPrivateHostname } from "../discovery/agent-card.js";
+/** Build a signed INK receipt envelope. */
+export async function buildReceipt(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("input must be a non-null object");
+    }
+    if (!(input.privateKey instanceof Uint8Array) || input.privateKey.length !== 32) {
+        throw new Error("input.privateKey must be a 32-byte Uint8Array");
+    }
+    const now = new Date().toISOString();
+    const messageHash = await computeMessageHash(input.messageBody);
+    const nonce = crypto.randomUUID().replace(/-/g, "");
+    const unsigned = {
+        protocol: "ink/0.1",
+        type: "network.tulpa.receipt",
+        from: input.from,
+        to: input.to,
+        messageId: input.messageId,
+        disposition: input.disposition,
+        dispositionAt: now,
+        messageHash,
+        nonce,
+        timestamp: now,
+        ...(input.note ? { note: input.note } : {}),
+    };
+    const signature = await signMessage(unsigned, input.privateKey);
+    return { ...unsigned, signature };
+}
+/** Loop prevention: don't send receipts for receipts or audit messages. */
+const NO_RECEIPT_TYPES = new Set([
+    "network.tulpa.receipt",
+    "network.tulpa.audit_query",
+    "network.tulpa.audit_response",
+    "network.tulpa.audit_submit",
+    "network.tulpa.audit_inclusion",
+]);
+export function shouldSendReceipt(intentOrType) {
+    return !NO_RECEIPT_TYPES.has(intentOrType);
+}
+/** Fire-and-forget POST of a receipt with INK request signature. Never throws.
+ *
+ *  Endpoint MUST be an absolute `https://` URL. Other schemes (file://, data:,
+ *  blob:, http://) are rejected silently to prevent SSRF and local-file
+ *  exfiltration when integrators pass peer-supplied URLs without sanitising.
+ *
+ *  Mirrors the SSRF defenses in fetchAgentCard: https-only, no userinfo,
+ *  literal-hostname allowlist excluding private/loopback/special-use, no
+ *  redirect following, request timeout. DNS rebinding is still the
+ *  integrator's responsibility — pass a connect-time-pinning `fetchFn`
+ *  when the endpoint is not fully trusted. */
+export async function sendReceiptFireAndForget(endpoint, receipt, privateKey, fetchFn = globalThis.fetch, signingKeyId, options) {
+    try {
+        let url;
+        try {
+            url = new URL(endpoint);
+        }
+        catch {
+            return;
+        }
+        if (url.protocol !== "https:")
+            return;
+        if (url.username || url.password)
+            return;
+        if (!options?.allowPrivateHosts && isPrivateHostname(url.hostname))
+            return;
+        const sig = await signInkMessage({
+            method: "POST",
+            path: url.pathname,
+            recipientDid: receipt.to,
+            body: receipt,
+            timestamp: receipt.timestamp,
+        }, privateKey);
+        await fetchFn(endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": buildAuthHeader(sig, signingKeyId),
+            },
+            body: JSON.stringify(receipt),
+            redirect: "manual",
+            signal: AbortSignal.timeout(5000),
+        });
+    }
+    catch {
+        // Fire-and-forget — swallow errors
+    }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Transport-bound authorization for INK delegation chains.
+ *
+ * Ensures delegation tokens are only valid on the transports they were
+ * issued for. Implements §7 of the INK Containment spec with version-gated
+ * migration for legacy tokens.
+ */
+import type { InkTransport } from "../models/ink-handshake.js";
+/**
+ * Permissive transport set for legacy tokens during the 90-day migration window.
+ * Matches the set of transports that existed before transport scoping was introduced.
+ */
+export declare const LEGACY_MIGRATION_TRANSPORTS: InkTransport[];
+/**
+ * Hard deadline for the legacy transport migration window.
+ * After this date, tokens without tokenVersion get the strict default.
+ */
+export declare const LEGACY_MIGRATION_DEADLINE: Date;
+/**
+ * Resolve the effective allowed transports for a delegation token.
+ *
+ * Rules (per spec §1.2):
+ * - Explicit allowedTransports always wins
+ * - v0.3+ tokens without allowedTransports default to ["ink_http"]
+ * - Legacy tokens (no tokenVersion) default to permissive set before the
+ *   migration deadline (2026-07-01), then ["ink_http"] after
+ */
+export declare function resolveEffectiveTransports(allowedTransports: InkTransport[] | undefined, tokenVersion: string | undefined, now?: Date): InkTransport[];
+/**
+ * Check if the current invocation transport is allowed by the delegation token.
+ */
+export declare function checkTransportAllowed(currentTransport: InkTransport, allowedTransports: InkTransport[]): {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: "transport_scope_violation";
+};
+/**
+ * Check that a child delegation hop's transports are a subset of the parent's.
+ * Each hop can only narrow, never widen the transport scope.
+ */
+export declare function checkTransportAttenuation(parentTransports: InkTransport[], childTransports: InkTransport[]): {
+    valid: true;
+} | {
+    valid: false;
+    addedTransports: InkTransport[];
+};

package/dist/ink/transport-auth.js

@@ -0,0 +1,77 @@
+/**
+ * Transport-bound authorization for INK delegation chains.
+ *
+ * Ensures delegation tokens are only valid on the transports they were
+ * issued for. Implements §7 of the INK Containment spec with version-gated
+ * migration for legacy tokens.
+ */
+/**
+ * Permissive transport set for legacy tokens during the 90-day migration window.
+ * Matches the set of transports that existed before transport scoping was introduced.
+ */
+export const LEGACY_MIGRATION_TRANSPORTS = [
+    "ink_http",
+    "extension_api",
+    "voice",
+    "line_phone",
+];
+/**
+ * Hard deadline for the legacy transport migration window.
+ * After this date, tokens without tokenVersion get the strict default.
+ */
+export const LEGACY_MIGRATION_DEADLINE = new Date("2026-07-01T00:00:00Z");
+/**
+ * Resolve the effective allowed transports for a delegation token.
+ *
+ * Rules (per spec §1.2):
+ * - Explicit allowedTransports always wins
+ * - v0.3+ tokens without allowedTransports default to ["ink_http"]
+ * - Legacy tokens (no tokenVersion) default to permissive set before the
+ *   migration deadline (2026-07-01), then ["ink_http"] after
+ */
+export function resolveEffectiveTransports(allowedTransports, tokenVersion, now = new Date()) {
+    // Distinguish "field absent" from "field present and empty". An
+    // explicit empty array is a "this token allows no transports"
+    // statement — it MUST stay empty, never fall through to the legacy
+    // permissive set. Treating [] as "absent" would broaden a token that
+    // its issuer intended to deny.
+    if (Array.isArray(allowedTransports)) {
+        return [...allowedTransports];
+    }
+    // v0.3+ token without explicit transports: strict default.
+    // Distinguish "field absent" (undefined) from "field present but
+    // malformed/empty". A token that supplies `tokenVersion: ""` is not
+    // a legacy token — it is a malformed new token. Treat anything
+    // present-and-not-undefined as a new token so a bad version string
+    // can't broaden transport scope during the migration window.
+    if (tokenVersion !== undefined) {
+        return ["ink_http"];
+    }
+    // Legacy token (tokenVersion truly absent): check against hard
+    // migration deadline.
+    if (now >= LEGACY_MIGRATION_DEADLINE) {
+        return ["ink_http"];
+    }
+    return [...LEGACY_MIGRATION_TRANSPORTS];
+}
+/**
+ * Check if the current invocation transport is allowed by the delegation token.
+ */
+export function checkTransportAllowed(currentTransport, allowedTransports) {
+    if (allowedTransports.includes(currentTransport)) {
+        return { allowed: true };
+    }
+    return { allowed: false, reason: "transport_scope_violation" };
+}
+/**
+ * Check that a child delegation hop's transports are a subset of the parent's.
+ * Each hop can only narrow, never widen the transport scope.
+ */
+export function checkTransportAttenuation(parentTransports, childTransports) {
+    const parentSet = new Set(parentTransports);
+    const added = childTransports.filter((t) => !parentSet.has(t));
+    if (added.length > 0) {
+        return { valid: false, addedTransports: added };
+    }
+    return { valid: true };
+}