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

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

@@ -0,0 +1,237 @@
+/**
+ * Capability-gated Agent Card discovery.
+ *
+ * Implements §6 of the INK Containment spec:
+ * - Redacted cards for unauthenticated requests on non-public visibility
+ * - Authenticated card query endpoint schemas
+ * - Access denial response schemas
+ */
+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";
+export interface RedactedAgentCard {
+    type: "tulpa.agent.card";
+    version: "1.0";
+    agentId: string;
+    displayName?: string;
+    visibility: "network_only" | "capability_gated";
+    supportsInk: true;
+    discoveryMode: "authenticate_for_details";
+    /**
+     * Bootstrap / legacy single public key. Preserved so peers can still verify
+     * Ed25519 signatures from cards without a full keys block.
+     */
+    publicKeyMultibase: string;
+    /**
+     * Authoritative signing key set (rotation). Public material only — revealing
+     * these is safe and necessary so peers can discover key rotations even when
+     * the rest of the Card is gated. Without this, an agent that rotated to a
+     * new key under network_only / capability_gated visibility would be
+     * unverifiable to first-contact peers.
+     */
+    keys?: {
+        signing: Array<{
+            keyId: string;
+            publicKeyMultibase: string;
+            status: "active" | "retired" | "revoked";
+            /** Validity-window fields are preserved in the redacted card so a
+             * first-contact peer that only ever sees the redacted form still
+             * enforces the same `[validFrom, validUntil]` bound the full card
+             * would. Stripping them creates a softer verification path. */
+            validFrom?: string;
+            validUntil?: string;
+            revokedAt?: string;
+        }>;
+    };
+    updatedAt: string;
+}
+/**
+ * Build a redacted Agent Card from a full card.
+ *
+ * Strips capabilities, endpoints, availability, profile, and other
+ * sensitive-on-a-closed-card fields. **Public signing keys are preserved**:
+ * Ed25519 public keys are not secrets — they are the identity. Hiding them
+ * would prevent peers from verifying signatures across key rotation when the
+ * full Card is gated.
+ */
+export declare function buildRedactedCard(card: AgentCard): RedactedAgentCard;
+export declare const AgentCardQuerySchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"ink/0.1">;
+    type: z.ZodLiteral<"network.tulpa.agent_card_query">;
+    from: z.ZodString;
+    nonce: z.ZodString;
+    timestamp: z.ZodString;
+    requestedFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AgentCardQuery = z.infer<typeof AgentCardQuerySchema>;
+export declare const AgentCardResponseSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"ink/0.1">;
+    type: z.ZodLiteral<"network.tulpa.agent_card_response">;
+    card: 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;
+        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>;
+    grantedFields: z.ZodArray<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type AgentCardResponse = z.infer<typeof AgentCardResponseSchema>;
+export declare const AgentCardDeniedSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"ink/0.1">;
+    type: z.ZodLiteral<"network.tulpa.agent_card_denied">;
+    reason: z.ZodEnum<{
+        unknown_requester: "unknown_requester";
+        insufficient_trust: "insufficient_trust";
+        not_connected: "not_connected";
+    }>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type AgentCardDenied = z.infer<typeof AgentCardDeniedSchema>;
+/**
+ * Determine whether an unauthenticated GET should return a full card
+ * or a redacted card based on visibility setting.
+ */
+export declare function shouldRedactOnGet(visibility: AgentCardVisibility): boolean;

package/dist/ink/discovery-gating.js

@@ -0,0 +1,91 @@
+/**
+ * Capability-gated Agent Card discovery.
+ *
+ * Implements §6 of the INK Containment spec:
+ * - Redacted cards for unauthenticated requests on non-public visibility
+ * - Authenticated card query endpoint schemas
+ * - Access denial response schemas
+ */
+import { z } from "zod";
+import { AgentCardSchema } from "../models/agent-card.js";
+export { AgentCardVisibilitySchema } from "../models/ink-handshake.js";
+/**
+ * Build a redacted Agent Card from a full card.
+ *
+ * Strips capabilities, endpoints, availability, profile, and other
+ * sensitive-on-a-closed-card fields. **Public signing keys are preserved**:
+ * Ed25519 public keys are not secrets — they are the identity. Hiding them
+ * would prevent peers from verifying signatures across key rotation when the
+ * full Card is gated.
+ */
+export function buildRedactedCard(card) {
+    // `visibility` is typed on AgentCard but a malformed runtime value can
+    // still slip through (e.g. a card deserialised without schema validation).
+    // Default to `capability_gated` — the least-privilege visibility — when
+    // 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",
+        version: "1.0",
+        agentId: card.agentId,
+        displayName: card.displayName,
+        supportsInk: true,
+        discoveryMode: "authenticate_for_details",
+        visibility,
+        publicKeyMultibase: card.publicKeyMultibase,
+        updatedAt: new Date().toISOString(),
+    };
+    // Preserve `keys.signing` on PRESENCE, not on truthiness/length.
+    // An empty signing array is an authoritative "no usable signing
+    // keys" statement (e.g. all keys revoked) and the verifier's key
+    // rotation authority rule treats it as a reject-all signal. Dropping
+    // the field here would let peers fall back to publicKeyMultibase or
+    // bootstrap derivation, undoing the rotation. See
+    // multi-key-verify and middleware/ink-auth for the authority rule.
+    if (Array.isArray(card.keys?.signing)) {
+        out.keys = {
+            signing: card.keys.signing.map((k) => ({
+                keyId: k.keyId,
+                publicKeyMultibase: k.publicKeyMultibase,
+                status: k.status,
+                // Preserve validity / revocation metadata: these are public
+                // facts about the key, not secrets, and a redacted card must
+                // not be weaker than the full card for signature verification.
+                validFrom: k.validFrom,
+                validUntil: k.validUntil,
+                revokedAt: k.revokedAt,
+            })),
+        };
+    }
+    return out;
+}
+// ── Query/Response schemas ──
+export const AgentCardQuerySchema = z.object({
+    protocol: z.literal("ink/0.1"),
+    type: z.literal("network.tulpa.agent_card_query"),
+    from: z.string(),
+    nonce: z.string(),
+    timestamp: z.string().datetime(),
+    requestedFields: z.array(z.string()).optional(),
+});
+export const AgentCardResponseSchema = z.object({
+    protocol: z.literal("ink/0.1"),
+    type: z.literal("network.tulpa.agent_card_response"),
+    card: AgentCardSchema,
+    grantedFields: z.array(z.string()),
+    timestamp: z.string().datetime(),
+});
+export const AgentCardDeniedSchema = z.object({
+    protocol: z.literal("ink/0.1"),
+    type: z.literal("network.tulpa.agent_card_denied"),
+    reason: z.enum(["unknown_requester", "insufficient_trust", "not_connected"]),
+    timestamp: z.string().datetime(),
+});
+// ── Visibility check ──
+/**
+ * Determine whether an unauthenticated GET should return a full card
+ * or a redacted card based on visibility setting.
+ */
+export function shouldRedactOnGet(visibility) {
+    return visibility !== "public";
+}

package/dist/ink/handshake-budget.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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
+ */
+import type { InkBackoffHint } from "../models/ink-handshake.js";
+export interface BudgetCheckResult {
+    allowed: boolean;
+    reason?: string;
+    backoffHint?: InkBackoffHint;
+    silentDrop?: boolean;
+}
+export interface HandshakeBudgetConfig {
+    maxChallenges?: number;
+    maxTotalTransitions?: number;
+    maxIntentsPerMinute?: number;
+    maxHandshakeMsgsPerMinute?: number;
+    maxCorrelations?: number;
+    maxSenders?: number;
+    maxRejectionEntries?: number;
+}
+export declare class HandshakeBudgetTracker {
+    private correlations;
+    private senders;
+    private rejectionsSent;
+    private senderRejectionsSent;
+    private readonly maxChallenges;
+    private readonly maxTotalTransitions;
+    private readonly maxIntentsPerMinute;
+    private readonly maxHandshakeMsgsPerMinute;
+    private readonly maxCorrelations;
+    private readonly maxSenders;
+    private readonly maxRejectionEntries;
+    private checkCounter;
+    constructor(config?: HandshakeBudgetConfig);
+    /**
+     * 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: {
+        correlationId: string;
+        fromDid: string;
+        messageType: "intent" | "challenge" | "rejection" | "resolution";
+        intentExpiresAt?: string;
+    }): BudgetCheckResult;
+    /**
+     * 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: {
+        correlationId: string;
+        fromDid: string;
+        messageType: "intent" | "challenge" | "rejection" | "resolution";
+        intentExpiresAt?: string;
+    }): BudgetCheckResult;
+    checkAndRecord(params: {
+        correlationId: string;
+        fromDid: string;
+        messageType: "intent" | "challenge" | "rejection" | "resolution";
+        intentExpiresAt?: string;
+    }): BudgetCheckResult;
+    private checkOrRecord;
+    pruneExpired(): void;
+    private checkSenderLimits;
+    private makeSenderRejection;
+    private recordSenderActivity;
+    private makeRejection;
+    private enforceRejectionBounds;
+    private enforceSenderBounds;
+    private enforceMemoryBounds;
+}