a1-ai 2.8.0

package/dist/esm/middleware.d.ts

@@ -0,0 +1,159 @@
+/**
+ * a1 — Express, Fastify, and generic Node.js HTTP middleware.
+ *
+ * Drop-in request lifecycle guards that enforce A1 passport-level capability
+ * narrowing on every incoming request before route handlers execute.
+ *
+ * @example Express
+ * ```ts
+ * import express from "express";
+ * import { A1Middleware } from "a1/middleware";
+ * import { A1Client } from "a1";
+ *
+ * const client = new A1Client("http://localhost:8080");
+ * const a1mw   = new A1Middleware(client);
+ *
+ * app.post("/trade", a1mw.guard("trade.equity"), async (req, res) => {
+ *   // req.a1 is populated with PassportReceipt
+ *   res.json({ ok: true });
+ * });
+ * ```
+ *
+ * @example Fastify
+ * ```ts
+ * import Fastify from "fastify";
+ * import { A1FastifyPlugin } from "a1/middleware";
+ *
+ * const app = Fastify();
+ * await app.register(A1FastifyPlugin, { gatewayUrl: "http://localhost:8080" });
+ *
+ * app.post("/trade", { preHandler: app.a1.guard("trade.equity") }, handler);
+ * ```
+ */
+import type { A1Client } from "./index.js";
+/** A parsed A1 PassportReceipt attached to the request by the middleware. */
+export interface A1RequestReceipt {
+    passport_namespace: string;
+    fingerprint_hex: string;
+    capability_mask_hex: string;
+    narrowing_commitment_hex: string;
+    chain_depth: number;
+    verified_at_unix: number;
+}
+/** Options for the middleware guard. */
+export interface GuardOptions {
+    /** Override the default chain extractor for this route. */
+    extractChain?: (req: unknown) => unknown;
+    /** Override the default executor key extractor. */
+    extractExecutorPk?: (req: unknown) => string;
+    /** Intent parameter bindings for the capability check. */
+    params?: Record<string, string>;
+    /** Whether to attach the full VerifiedToken to the request for session caching. */
+    returnToken?: boolean;
+}
+/**
+ * Express-compatible middleware factory for A1 capability enforcement.
+ *
+ * Attaches a `PassportReceipt` to `req.a1` on success. On failure, calls
+ * `next(err)` with a structured error so your error handler can render the
+ * appropriate HTTP response.
+ */
+export declare class A1Middleware {
+    private readonly client;
+    private _extractChain;
+    private _extractExecutorPk;
+    constructor(client: A1Client);
+    /**
+     * Override the default chain extractor for all routes protected by this
+     * middleware instance.
+     */
+    withChainExtractor(fn: (req: unknown) => unknown): this;
+    /**
+     * Override the default executor key extractor for all routes.
+     */
+    withExecutorPkExtractor(fn: (req: unknown) => string): this;
+    /**
+     * Returns an Express request handler that enforces `capability` before the
+     * route handler runs.
+     *
+     * Attaches the `PassportReceipt` to `(req as any).a1` on success.
+     */
+    guard(capability: string, opts?: GuardOptions): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+}
+export interface JwtExchangeOptions {
+    /** The raw JWT bearer token from the enterprise IdP. */
+    token: string;
+    /** Ed25519 public key hex of the agent receiving the delegation cert. */
+    delegatePkHex: string;
+    /** Capability names to grant (must be in A1_JWT_ALLOWED_CAPS on gateway). */
+    capabilities: string[];
+    /** Cert lifetime. Defaults to 3600. Capped at JWT exp - now. */
+    ttlSeconds?: number;
+    /** Opaque request ID forwarded to gateway logs. */
+    requestId?: string;
+}
+export interface JwtExchangeResult {
+    fingerprintHex: string;
+    scopeRootHex: string;
+    expiresAtUnix: number;
+    jwtSubject: string;
+    jwtIssuer: string;
+    capabilities: string[];
+}
+/**
+ * Exchange an OIDC/OAuth2 JWT bearer token for an A1 DelegationCert.
+ *
+ * Enterprise services that authenticate users via SSO can call this to
+ * bootstrap an A1 delegation chain from an existing JWT without a separate
+ * key ceremony.  Requires `A1_JWT_JWKS_URL` to be configured on the gateway.
+ *
+ * @example
+ * ```ts
+ * const cert = await exchangeJwt(client, {
+ *   token:         idToken,
+ *   delegatePkHex: agentPublicKey,
+ *   capabilities:  ["trade.equity"],
+ *   ttlSeconds:    3600,
+ * });
+ * ```
+ */
+export declare function exchangeJwt(client: A1Client, opts: JwtExchangeOptions): Promise<JwtExchangeResult>;
+export interface WebhookEvent {
+    event: string;
+    schema_ver: number;
+    provenance: string;
+    timestamp: number;
+    authorized: boolean;
+    chain_depth: number;
+    fingerprint: string;
+    intent_hex: string;
+    namespace?: string;
+    error_code?: string;
+    request_id?: string;
+    tenant_id?: string;
+}
+/**
+ * Verify the BLAKE3-HMAC signature on an inbound A1 webhook delivery.
+ *
+ * Call this at the top of your webhook endpoint handler before processing
+ * the event payload.  Returns `true` when the signature is valid.
+ *
+ * @example Express webhook receiver
+ * ```ts
+ * app.post("/webhook/a1", express.raw({ type: "application/json" }), (req, res) => {
+ *   const sig = req.headers["x-a1-webhook-signature"] as string;
+ *   if (!verifyWebhookSignature(req.body, sig, process.env.A1_WEBHOOK_SECRET!)) {
+ *     return res.status(401).json({ error: "invalid signature" });
+ *   }
+ *   const event: WebhookEvent = JSON.parse(req.body.toString());
+ *   // ... handle event
+ *   res.json({ ok: true });
+ * });
+ * ```
+ *
+ * Note: The BLAKE3 implementation requires a WASM or native binding.  If your
+ * environment does not support it, verify using the raw BLAKE3 hex from the
+ * header against your own implementation.
+ */
+export declare function verifyWebhookSignature(body: Buffer | string, header: string, secret: string): boolean;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/esm/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/esm/middleware.js

@@ -0,0 +1,201 @@
+/**
+ * a1 — Express, Fastify, and generic Node.js HTTP middleware.
+ *
+ * Drop-in request lifecycle guards that enforce A1 passport-level capability
+ * narrowing on every incoming request before route handlers execute.
+ *
+ * @example Express
+ * ```ts
+ * import express from "express";
+ * import { A1Middleware } from "a1/middleware";
+ * import { A1Client } from "a1";
+ *
+ * const client = new A1Client("http://localhost:8080");
+ * const a1mw   = new A1Middleware(client);
+ *
+ * app.post("/trade", a1mw.guard("trade.equity"), async (req, res) => {
+ *   // req.a1 is populated with PassportReceipt
+ *   res.json({ ok: true });
+ * });
+ * ```
+ *
+ * @example Fastify
+ * ```ts
+ * import Fastify from "fastify";
+ * import { A1FastifyPlugin } from "a1/middleware";
+ *
+ * const app = Fastify();
+ * await app.register(A1FastifyPlugin, { gatewayUrl: "http://localhost:8080" });
+ *
+ * app.post("/trade", { preHandler: app.a1.guard("trade.equity") }, handler);
+ * ```
+ */
+// ── Chain / executor extractors ───────────────────────────────────────────────
+/**
+ * Default chain extractor: reads the signed chain from the request body
+ * under the key `signed_chain` or `chain`.
+ */
+function defaultExtractChain(req) {
+    const body = req["body"];
+    return body?.["signed_chain"] ?? body?.["chain"];
+}
+/**
+ * Default executor key extractor: reads from request body under
+ * `executor_pk_hex` or from the `X-A1-Executor-PK` request header.
+ */
+function defaultExtractExecutorPk(req) {
+    const body = req["body"];
+    const fromBody = typeof body?.["executor_pk_hex"] === "string" ? body["executor_pk_hex"] : undefined;
+    if (fromBody)
+        return fromBody;
+    const headers = req["headers"];
+    return headers?.["x-a1-executor-pk"] ?? "";
+}
+// ── A1Middleware (Express-compatible) ─────────────────────────────────────────
+/**
+ * Express-compatible middleware factory for A1 capability enforcement.
+ *
+ * Attaches a `PassportReceipt` to `req.a1` on success. On failure, calls
+ * `next(err)` with a structured error so your error handler can render the
+ * appropriate HTTP response.
+ */
+export class A1Middleware {
+    client;
+    _extractChain = defaultExtractChain;
+    _extractExecutorPk = defaultExtractExecutorPk;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Override the default chain extractor for all routes protected by this
+     * middleware instance.
+     */
+    withChainExtractor(fn) {
+        this._extractChain = fn;
+        return this;
+    }
+    /**
+     * Override the default executor key extractor for all routes.
+     */
+    withExecutorPkExtractor(fn) {
+        this._extractExecutorPk = fn;
+        return this;
+    }
+    /**
+     * Returns an Express request handler that enforces `capability` before the
+     * route handler runs.
+     *
+     * Attaches the `PassportReceipt` to `(req as any).a1` on success.
+     */
+    guard(capability, opts = {}) {
+        const extractChain = opts.extractChain ?? this._extractChain;
+        const extractExecutorPk = opts.extractExecutorPk ?? this._extractExecutorPk;
+        const client = this.client;
+        return async (req, _res, next) => {
+            try {
+                const chain = extractChain(req);
+                const executorPk = extractExecutorPk(req);
+                if (!chain) {
+                    const err = Object.assign(new Error("A1: missing signed_chain in request body"), {
+                        status: 401,
+                        code: "MISSING_CHAIN",
+                    });
+                    return next(err);
+                }
+                const result = await client.authorize({
+                    chain: chain,
+                    intentName: capability,
+                    intentParams: opts.params,
+                    executorPkHex: executorPk,
+                    returnToken: opts.returnToken ?? false,
+                });
+                // Attach receipt for downstream handlers
+                req["a1"] = result;
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    }
+}
+/**
+ * Exchange an OIDC/OAuth2 JWT bearer token for an A1 DelegationCert.
+ *
+ * Enterprise services that authenticate users via SSO can call this to
+ * bootstrap an A1 delegation chain from an existing JWT without a separate
+ * key ceremony.  Requires `A1_JWT_JWKS_URL` to be configured on the gateway.
+ *
+ * @example
+ * ```ts
+ * const cert = await exchangeJwt(client, {
+ *   token:         idToken,
+ *   delegatePkHex: agentPublicKey,
+ *   capabilities:  ["trade.equity"],
+ *   ttlSeconds:    3600,
+ * });
+ * ```
+ */
+export async function exchangeJwt(client, opts) {
+    // Access the internal fetch helper via the public API surface
+    const rawResult = await client._post("/v1/jwt/exchange", {
+        token: opts.token,
+        delegate_pk_hex: opts.delegatePkHex,
+        capabilities: opts.capabilities,
+        ttl_seconds: opts.ttlSeconds ?? 3600,
+        request_id: opts.requestId,
+    });
+    const r = rawResult;
+    return {
+        fingerprintHex: r["fingerprint_hex"],
+        scopeRootHex: r["scope_root_hex"],
+        expiresAtUnix: r["expires_at_unix"],
+        jwtSubject: r["jwt_subject"],
+        jwtIssuer: r["jwt_issuer"],
+        capabilities: r["capabilities"],
+    };
+}
+/**
+ * Verify the BLAKE3-HMAC signature on an inbound A1 webhook delivery.
+ *
+ * Call this at the top of your webhook endpoint handler before processing
+ * the event payload.  Returns `true` when the signature is valid.
+ *
+ * @example Express webhook receiver
+ * ```ts
+ * app.post("/webhook/a1", express.raw({ type: "application/json" }), (req, res) => {
+ *   const sig = req.headers["x-a1-webhook-signature"] as string;
+ *   if (!verifyWebhookSignature(req.body, sig, process.env.A1_WEBHOOK_SECRET!)) {
+ *     return res.status(401).json({ error: "invalid signature" });
+ *   }
+ *   const event: WebhookEvent = JSON.parse(req.body.toString());
+ *   // ... handle event
+ *   res.json({ ok: true });
+ * });
+ * ```
+ *
+ * Note: The BLAKE3 implementation requires a WASM or native binding.  If your
+ * environment does not support it, verify using the raw BLAKE3 hex from the
+ * header against your own implementation.
+ */
+export function verifyWebhookSignature(body, header, secret) {
+    // The signature header format is "sha256=<hex>".
+    // Recompute and compare via constant-time comparison.
+    if (!header.startsWith("sha256="))
+        return false;
+    const receivedHex = header.slice(7);
+    // Pure-JS BLAKE3 is ~100 LOC; we defer to the platform crypto for HMAC-SHA256
+    // as a compatible fallback (the gateway accepts both in future versions).
+    // Production deployments should install @noble/hashes for full BLAKE3 support.
+    try {
+        const crypto = require("crypto");
+        const bodyBytes = typeof body === "string" ? Buffer.from(body) : body;
+        const derivedKey = crypto.createHash("sha256").update(`a1::64796f6c6f::webhook::${secret}::v2.8.0`).digest();
+        const mac = crypto.createHmac("sha256", derivedKey).update(bodyBytes).digest("hex");
+        return crypto.timingSafeEqual(Buffer.from(mac, "hex"), Buffer.from(receivedHex, "hex"));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=middleware.js.map

package/dist/esm/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA4BH,iFAAiF;AAEjF;;;GAGG;AACH,SAAS,mBAAmB,CAAC,GAAY;IACvC,MAAM,IAAI,GAAI,GAA+B,CAAC,MAAM,CAAwC,CAAC;IAC7F,OAAO,IAAI,EAAE,CAAC,cAAc,CAAC,IAAI,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,SAAS,wBAAwB,CAAC,GAAY;IAC5C,MAAM,IAAI,GAAI,GAA+B,CAAC,MAAM,CAAwC,CAAC;IAC7F,MAAM,QAAQ,GAAG,OAAO,IAAI,EAAE,CAAC,iBAAiB,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACrG,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,OAAO,GAAI,GAA+B,CAAC,SAAS,CAAwC,CAAC;IACnG,OAAQ,OAAO,EAAE,CAAC,kBAAkB,CAAwB,IAAI,EAAE,CAAC;AACrE,CAAC;AAED,iFAAiF;AAEjF;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACN,MAAM,CAAW;IAC1B,aAAa,GAA8B,mBAAmB,CAAC;IAC/D,kBAAkB,GAA6B,wBAAwB,CAAC;IAEhF,YAAY,MAAgB;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,kBAAkB,CAAC,EAA6B;QAC9C,IAAI,CAAC,aAAa,GAAG,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,uBAAuB,CAAC,EAA4B;QAClD,IAAI,CAAC,kBAAkB,GAAG,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAkB,EAAE,OAAqB,EAAE;QAC/C,MAAM,YAAY,GAAO,IAAI,CAAC,YAAY,IAAQ,IAAI,CAAC,aAAa,CAAC;QACrE,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,kBAAkB,CAAC;QAC5E,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAE3B,OAAO,KAAK,EAAE,GAAY,EAAE,IAAa,EAAE,IAA6B,EAAE,EAAE;YAC1E,IAAI,CAAC;gBACH,MAAM,KAAK,GAAS,YAAY,CAAC,GAAG,CAAC,CAAC;gBACtC,MAAM,UAAU,GAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;gBAE3C,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,0CAA0C,CAAC,EAAE;wBAC/E,MAAM,EAAE,GAAG;wBACX,IAAI,EAAI,eAAe;qBACxB,CAAC,CAAC;oBACH,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;gBACnB,CAAC;gBAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC;oBACpC,KAAK,EAAW,KAAwD;oBACxE,UAAU,EAAM,UAAU;oBAC1B,YAAY,EAAI,IAAI,CAAC,MAAM;oBAC3B,aAAa,EAAG,UAAU;oBAC1B,WAAW,EAAK,IAAI,CAAC,WAAW,IAAI,KAAK;iBAC1C,CAAC,CAAC;gBAEH,yCAAyC;gBACxC,GAA+B,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;gBAEhD,IAAI,EAAE,CAAC;YACT,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,IAAI,CAAC,GAAG,CAAC,CAAC;YACZ,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;CACF;AA0BD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAgB,EAChB,IAA0B;IAE1B,8DAA8D;IAC9D,MAAM,SAAS,GAAG,MAAO,MAEvB,CAAC,KAAK,CAAC,kBAAkB,EAAE;QAC3B,KAAK,EAAY,IAAI,CAAC,KAAK;QAC3B,eAAe,EAAE,IAAI,CAAC,aAAa;QACnC,YAAY,EAAK,IAAI,CAAC,YAAY;QAClC,WAAW,EAAM,IAAI,CAAC,UAAU,IAAI,IAAI;QACxC,UAAU,EAAO,IAAI,CAAC,SAAS;KAChC,CAAC,CAAC;IAEH,MAAM,CAAC,GAAG,SAAoC,CAAC;IAC/C,OAAO;QACL,cAAc,EAAE,CAAC,CAAC,iBAAiB,CAAW;QAC9C,YAAY,EAAI,CAAC,CAAC,gBAAgB,CAAY;QAC9C,aAAa,EAAG,CAAC,CAAC,iBAAiB,CAAW;QAC9C,UAAU,EAAM,CAAC,CAAC,aAAa,CAAe;QAC9C,SAAS,EAAO,CAAC,CAAC,YAAY,CAAgB;QAC9C,YAAY,EAAI,CAAC,CAAC,cAAc,CAAgB;KACjD,CAAC;AACJ,CAAC;AAmBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAA0B,EAC1B,MAAiB,EACjB,MAAiB;IAEjB,iDAAiD;IACjD,sDAAsD;IACtD,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,KAAK,CAAC;IAChD,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEpC,8EAA8E;IAC9E,0EAA0E;IAC1E,+EAA+E;IAC/E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,MAAM,SAAS,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACtE,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,4BAA4B,MAAM,UAAU,CAAC,CAAC,MAAM,EAAE,CAAC;QAC7G,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpF,OAAO,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;IAC1F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/esm/passport.d.ts

@@ -0,0 +1,109 @@
+/**
+ * a1 passport middleware for TypeScript/Node.js AI agent tools.
+ *
+ * Provides a one-function drop-in guard that enforces passport-level capability
+ * narrowing before any tool function executes. Works with OpenAI tool calls,
+ * LangChain tools, Vercel AI SDK, or any plain async function.
+ *
+ * @example
+ * ```ts
+ * import { withA1Passport, PassportClient } from "a1/passport";
+ *
+ * const client = new PassportClient("http://localhost:8080");
+ *
+ * const guardedTool = withA1Passport(executeTrade, {
+ *   client,
+ *   capability: "trade.equity",
+ * });
+ * ```
+ */
+export interface PassportReceipt {
+    passport_namespace: string;
+    fingerprint_hex: string;
+    capability_mask_hex: string;
+    narrowing_commitment_hex: string;
+    chain_depth: number;
+}
+export interface AuthorizePassportRequest {
+    chain: unknown;
+    intent_name: string;
+    executor_pk_hex: string;
+    intent_params?: Record<string, unknown>;
+}
+export interface PassportGuardOptions {
+    /** A PassportClient pointed at the a1 gateway. */
+    client: PassportClient;
+    /** The capability name to enforce, e.g. `"trade.equity"`. */
+    capability: string;
+    /**
+     * Name of the property in the tool's arguments object that carries the
+     * signed delegation chain. Defaults to `"signed_chain"`.
+     */
+    chainKey?: string;
+    /**
+     * Name of the property in the tool's arguments object carrying the executor
+     * public key hex. Defaults to `"executor_pk_hex"`.
+     */
+    executorKey?: string;
+}
+export declare class PassportError extends Error {
+    readonly errorCode: string;
+    readonly httpStatus: number;
+    constructor(message: string, errorCode?: string, httpStatus?: number);
+}
+/**
+ * Gateway client with passport-aware authorization.
+ *
+ * Wraps the a1 gateway `/v1/passport/authorize` endpoint with typed inputs/outputs
+ * and structured error propagation.
+ */
+export declare class PassportClient {
+    private readonly base;
+    private readonly headers;
+    private readonly timeoutMs;
+    constructor(baseUrl: string, options?: {
+        headers?: Record<string, string>;
+        timeoutMs?: number;
+    });
+    authorize(req: AuthorizePassportRequest): Promise<PassportReceipt>;
+}
+/**
+ * Wrap any async function with a passport capability guard.
+ *
+ * The wrapped function receives the same arguments as the original. Before
+ * delegating to the original, it extracts the signed chain and executor public
+ * key from the first argument object and calls the gateway. On authorization
+ * failure it throws `PassportError`.
+ *
+ * @example
+ * ```ts
+ * const guardedTrade = withA1Passport(executeTrade, {
+ *   client,
+ *   capability: "trade.equity",
+ * });
+ *
+ * // The caller passes signed_chain and executor_pk_hex alongside the tool args:
+ * const result = await guardedTrade({
+ *   symbol: "AAPL",
+ *   qty: 10,
+ *   signed_chain: chain,
+ *   executor_pk_hex: agentPkHex,
+ * });
+ * ```
+ */
+export declare function withA1Passport<T extends Record<string, unknown>, R>(fn: (args: T) => Promise<R>, options: PassportGuardOptions): (args: T) => Promise<R>;
+/**
+ * Class-method decorator (Stage-3 decorators, TypeScript 5+).
+ *
+ * @example
+ * ```ts
+ * class TradingAgent {
+ *   @PassportGuard({ client, capability: "trade.equity" })
+ *   async executeTrade(args: { symbol: string; signed_chain: unknown; executor_pk_hex: string }) {
+ *     ...
+ *   }
+ * }
+ * ```
+ */
+export declare function PassportGuard(options: PassportGuardOptions): <T extends Record<string, unknown>, R>(originalMethod: (args: T) => Promise<R>, _context: ClassMethodDecoratorContext) => (args: T) => Promise<R>;
+//# sourceMappingURL=passport.d.ts.map

package/dist/esm/passport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passport.d.ts","sourceRoot":"","sources":["../../src/passport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,WAAW,eAAe;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,wBAAwB,EAAE,MAAM,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,MAAM,EAAE,cAAc,CAAC;IACvB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,SAAS,SAAmB,EAAE,UAAU,SAAM;CAM5E;AAID;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAOlE,SAAS,CAAC,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAAC,eAAe,CAAC;CA6CzE;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EACjE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,oBAAoB,GAC5B,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAsBzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,IACxC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EACnD,gBAAgB,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EACvC,UAAU,2BAA2B,KACpC,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAG3B"}

package/dist/esm/passport.js

@@ -0,0 +1,151 @@
+/**
+ * a1 passport middleware for TypeScript/Node.js AI agent tools.
+ *
+ * Provides a one-function drop-in guard that enforces passport-level capability
+ * narrowing before any tool function executes. Works with OpenAI tool calls,
+ * LangChain tools, Vercel AI SDK, or any plain async function.
+ *
+ * @example
+ * ```ts
+ * import { withA1Passport, PassportClient } from "a1/passport";
+ *
+ * const client = new PassportClient("http://localhost:8080");
+ *
+ * const guardedTool = withA1Passport(executeTrade, {
+ *   client,
+ *   capability: "trade.equity",
+ * });
+ * ```
+ */
+export class PassportError extends Error {
+    errorCode;
+    httpStatus;
+    constructor(message, errorCode = "PASSPORT_ERROR", httpStatus = 403) {
+        super(message);
+        this.name = "PassportError";
+        this.errorCode = errorCode;
+        this.httpStatus = httpStatus;
+    }
+}
+// ── PassportClient ────────────────────────────────────────────────────────────
+/**
+ * Gateway client with passport-aware authorization.
+ *
+ * Wraps the a1 gateway `/v1/passport/authorize` endpoint with typed inputs/outputs
+ * and structured error propagation.
+ */
+export class PassportClient {
+    base;
+    headers;
+    timeoutMs;
+    constructor(baseUrl, options = {}) {
+        this.base = baseUrl.replace(/\/$/, "");
+        this.headers = { "Content-Type": "application/json", ...options.headers };
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+    }
+    async authorize(req) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let resp;
+        try {
+            resp = await fetch(`${this.base}/v1/passport/authorize`, {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify({
+                    chain: req.chain,
+                    intent_name: req.intent_name,
+                    executor_pk_hex: req.executor_pk_hex,
+                    intent_params: req.intent_params ?? {},
+                }),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!resp.ok) {
+            let errorCode = "AUTHORIZATION_FAILED";
+            let message = `HTTP ${resp.status}`;
+            try {
+                const body = await resp.json();
+                if (typeof body["error"] === "string")
+                    message = body["error"];
+                if (typeof body["error_code"] === "string")
+                    errorCode = body["error_code"];
+            }
+            catch {
+                // ignore JSON parse failure
+            }
+            throw new PassportError(message, errorCode, resp.status);
+        }
+        const data = await resp.json();
+        const receipt = (data["receipt"] ?? data);
+        return {
+            passport_namespace: receipt["passport_namespace"] ?? "",
+            fingerprint_hex: receipt["fingerprint_hex"] ?? "",
+            capability_mask_hex: receipt["capability_mask_hex"] ?? "",
+            narrowing_commitment_hex: receipt["narrowing_commitment_hex"] ?? "",
+            chain_depth: receipt["chain_depth"] ?? 0,
+        };
+    }
+}
+// ── withA1Passport ─────────────────────────────────────────────────────────
+/**
+ * Wrap any async function with a passport capability guard.
+ *
+ * The wrapped function receives the same arguments as the original. Before
+ * delegating to the original, it extracts the signed chain and executor public
+ * key from the first argument object and calls the gateway. On authorization
+ * failure it throws `PassportError`.
+ *
+ * @example
+ * ```ts
+ * const guardedTrade = withA1Passport(executeTrade, {
+ *   client,
+ *   capability: "trade.equity",
+ * });
+ *
+ * // The caller passes signed_chain and executor_pk_hex alongside the tool args:
+ * const result = await guardedTrade({
+ *   symbol: "AAPL",
+ *   qty: 10,
+ *   signed_chain: chain,
+ *   executor_pk_hex: agentPkHex,
+ * });
+ * ```
+ */
+export function withA1Passport(fn, options) {
+    const { client, capability, chainKey = "signed_chain", executorKey = "executor_pk_hex" } = options;
+    return async function guardedFn(args) {
+        const chain = args[chainKey];
+        if (chain == null) {
+            throw new PassportError(`missing required argument '${chainKey}'`, "MISSING_CHAIN");
+        }
+        const executorPkHex = args[executorKey] ?? "";
+        await client.authorize({
+            chain,
+            intent_name: capability,
+            executor_pk_hex: executorPkHex,
+        });
+        return fn(args);
+    };
+}
+/**
+ * Class-method decorator (Stage-3 decorators, TypeScript 5+).
+ *
+ * @example
+ * ```ts
+ * class TradingAgent {
+ *   @PassportGuard({ client, capability: "trade.equity" })
+ *   async executeTrade(args: { symbol: string; signed_chain: unknown; executor_pk_hex: string }) {
+ *     ...
+ *   }
+ * }
+ * ```
+ */
+export function PassportGuard(options) {
+    return function (originalMethod, _context) {
+        return withA1Passport(originalMethod, options);
+    };
+}
+//# sourceMappingURL=passport.js.map

package/dist/esm/passport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passport.js","sourceRoot":"","sources":["../../src/passport.ts"],"names":[],"mappings":"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"}