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

package/src/ink/transport-auth.ts

@@ -1,96 +0,0 @@
-/**
- * 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 const LEGACY_MIGRATION_TRANSPORTS: InkTransport[] = [
-  "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: InkTransport[] | undefined,
-  tokenVersion: string | undefined,
-  now: Date = new Date(),
-): InkTransport[] {
-  // 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: InkTransport,
-  allowedTransports: InkTransport[],
-): { allowed: true } | { allowed: false; reason: "transport_scope_violation" } {
-  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: InkTransport[],
-  childTransports: InkTransport[],
-): { valid: true } | { valid: false; addedTransports: InkTransport[] } {
-  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 };
-}

package/src/middleware/ink-auth.ts

@@ -1,263 +0,0 @@
-import { verifyInkSignature, type InkSignInput, 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";
-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 async 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 }
-> {
-  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 as NonceStore).has === "function" &&
-    typeof (opts.nonceStore as NonceStore).add === "function";
-  if (opts.nonceStore !== "deferred" && !storeIsObject) {
-    return { valid: false, error: "nonce_handling_required" };
-  }
-  const usingNonceStore = storeIsObject;
-  let bodyNonce: string | undefined;
-  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: InkSignInput = {
-    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(): Promise<{ ok: true } | { ok: false; error: string }> {
-    if (!usingNonceStore) return { ok: true };
-    const store = opts.nonceStore as NonceStore;
-    const nonce = bodyNonce!;
-    let alreadySeen: boolean;
-    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: Uint8Array | null = 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/src/models/agent-card.ts

@@ -1,63 +0,0 @@
-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),
-  endpoint: z.string().url(),
-  publicKeyMultibase: z.string().startsWith("z"),
-  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(),
-});
-
-export type AgentCard = z.infer<typeof AgentCardSchema>;

package/src/models/ink-audit.ts

@@ -1,205 +0,0 @@
-import { z } from "zod";
-
-// ── INK Audit Event Types (INK Auditability §2) ──
-
-export const InkAuditEventTypeSchema = z.enum([
-  // Message lifecycle
-  "message.sent",
-  "message.received",
-  "message.queued",
-  "message.delivered",
-  "message.acted",
-  "message.rejected",
-  "message.expired",
-  "message.retracted",
-  // Receipt lifecycle
-  "receipt.sent",
-  "receipt.received",
-  // Delegation
-  "delegation.granted",
-  "delegation.used",
-  "delegation.revoked",
-  "delegation.expired",
-  // Connection
-  "connection.requested",
-  "connection.accepted",
-  "connection.declined",
-  // Verification
-  "signature.verified",
-  "signature.verified_retired",
-  "signature.failed",
-  "signature.revoked_rejected",
-  "replay.detected",
-  // Key lifecycle
-  "key.rotated",
-  "key.revoked",
-  // Introduction lifecycle
-  "introduction.requested",
-  "introduction.approved",
-  "introduction.declined",
-  "introduction.forwarded",
-  "introduction.completed",
-  "introduction.expired",
-  "introduction.receipt_sent",
-  "introduction.receipt_received",
-  // Enclave lifecycle
-  "enclave.requested",
-  "enclave.authorized",
-  "enclave.opened",
-  "enclave.operation_submitted",
-  "enclave.resolved",
-  "enclave.expired",
-  "enclave.aborted",
-  "enclave.receipt_sent",
-  "enclave.receipt_received",
-  // Containment (Phase 1)
-  "transport_scope_violation",
-  "handshake_rate_limited",
-  "handshake_budget_exhausted",
-  "discovery_query_received",
-  "discovery_query_granted",
-  "discovery_query_denied",
-]);
-
-export type InkAuditEventType = z.infer<typeof InkAuditEventTypeSchema>;
-
-// ── INK Audit Event (hash-chained, signed) ──
-
-export const InkAuditEventSchema = z.object({
-  id: z.string().min(1),
-  version: z.literal("ink-audit/1"),
-  agentId: z.string().min(1),
-  agentSignature: z.string().min(1),
-  sequence: z.number().int().positive(),
-  previousEventHash: z.string().regex(/^[0-9a-f]{64}$/).nullable(),
-  eventType: InkAuditEventTypeSchema,
-  timestamp: z.string().datetime(),
-  messageId: z.string().min(1).optional(),
-  correlationId: z.string().min(1).optional(),
-  counterpartyId: z.string().min(1).optional(),
-  signingKeyId: z.string().min(1).optional(),
-  data: z.record(z.unknown()).optional(),
-});
-
-export type InkAuditEvent = z.infer<typeof InkAuditEventSchema>;
-
-// ── Receipt (INK Auditability §1) ──
-
-export const InkReceiptDispositionSchema = z.enum([
-  "received",
-  "delivered",
-  "acted",
-  "rejected",
-  "expired",
-]);
-
-export type InkReceiptDisposition = z.infer<typeof InkReceiptDispositionSchema>;
-
-export const InkReceiptSchema = z.object({
-  protocol: z.literal("ink/0.1"),
-  type: z.literal("network.tulpa.receipt"),
-  from: z.string(),
-  to: z.string(),
-  messageId: z.string(),
-  disposition: InkReceiptDispositionSchema,
-  dispositionAt: z.string().datetime(),
-  note: z.string().max(500).optional(),
-  messageHash: z.string(),
-  nonce: z.string(),
-  timestamp: z.string().datetime(),
-  signature: z.string(),
-});
-
-export type InkReceipt = z.infer<typeof InkReceiptSchema>;
-
-// ── Audit Query (INK Auditability §3) ──
-
-export const InkAuditQuerySchema = z.object({
-  protocol: z.literal("ink/0.1"),
-  type: z.literal("network.tulpa.audit_query"),
-  from: z.string(),
-  to: z.string(),
-  messageId: z.string(),
-  nonce: z.string(),
-  timestamp: z.string().datetime(),
-});
-
-export type InkAuditQuery = z.infer<typeof InkAuditQuerySchema>;
-
-// ── Audit Response (INK Auditability §3) ──
-
-export const InkAuditResponseSchema = z.object({
-  protocol: z.literal("ink/0.1"),
-  type: z.literal("network.tulpa.audit_response"),
-  messageId: z.string(),
-  events: z.array(InkAuditEventSchema),
-  responseSignature: z.string(),
-});
-
-export type InkAuditResponse = z.infer<typeof InkAuditResponseSchema>;
-
-// ── Third-Party Audit Submit (INK Auditability §7.2) ──
-
-export const InkAuditSubmitSchema = z.object({
-  protocol: z.literal("ink/0.1"),
-  type: z.literal("network.tulpa.audit_submit"),
-  from: z.string().max(256),
-  to: z.string().max(256),
-  event: InkAuditEventSchema,
-  nonce: z.string().min(16).max(256),
-  timestamp: z.string().datetime(),
-});
-
-export type InkAuditSubmit = z.infer<typeof InkAuditSubmitSchema>;
-
-// ── Third-Party Audit Inclusion Receipt (INK Auditability §7.2) ──
-
-export const InkAuditInclusionSchema = z.object({
-  protocol: z.literal("ink/0.1"),
-  type: z.literal("network.tulpa.audit_inclusion"),
-  eventId: z.string(),
-  treeSize: z.number().int().positive(),
-  leafIndex: z.number().int().min(0),
-  rootHash: z.string(),
-  timestamp: z.string().datetime(),
-  serviceSignature: z.string(),
-});
-
-export type InkAuditInclusion = z.infer<typeof InkAuditInclusionSchema>;
-
-// ── Introduction Receipt (INK Introduction Receipts Extension §4) ──
-
-export const InkIntroductionReceiptStatusSchema = z.enum([
-  "approved",
-  "declined",
-  "forwarded",
-  "completed",
-  "expired",
-]);
-
-export type InkIntroductionReceiptStatus = z.infer<typeof InkIntroductionReceiptStatusSchema>;
-
-export const InkIntroductionReceiptSchema = z.object({
-  protocol: z.literal("ink/0.1"),
-  type: z.literal("network.tulpa.introduction_receipt"),
-  id: z.string(),
-  correlationId: z.string(),
-  from: z.string(),
-  to: z.string(),
-  requesterDid: z.string(),
-  introducerDid: z.string(),
-  beneficiaryDid: z.string(),
-  targetDid: z.string(),
-  status: InkIntroductionReceiptStatusSchema,
-  purpose: z.string().min(1).max(500),
-  nonce: z.string(),
-  timestamp: z.string().datetime(),
-  relatedIntentId: z.string().optional(),
-  relatedResolutionId: z.string().optional(),
-  note: z.string().max(500).optional(),
-  contextHash: z.string().optional(),
-  authorizationChainRef: z.string().optional(),
-  expiresAt: z.string().datetime().optional(),
-});
-
-export type InkIntroductionReceipt = z.infer<typeof InkIntroductionReceiptSchema>;