passcontrol 1.4.0 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -16,6 +16,35 @@ export interface PassControlOptions {
16
16
  /** Override the transport (tests / custom fetch). Defaults to global fetch. */
17
17
  fetch?: typeof fetch;
18
18
  }
19
+ /** A worker's side of a signed delegation (Bet D). */
20
+ export interface PassControlDelegationOptions {
21
+ gateway: string;
22
+ /** The chain the worker was handed, root first. */
23
+ chain: string[];
24
+ /** The worker's own private key. Its public half is the chain's last `sub`. */
25
+ workerPrivateKey: string;
26
+ refreshSkewSeconds?: number;
27
+ fetch?: typeof fetch;
28
+ }
29
+ export interface DelegateOptions {
30
+ /** The worker's public key. The worker keeps its private key; the parent never holds it. */
31
+ workerPublicKey: string;
32
+ scope: {
33
+ provider: ProviderId | string;
34
+ models: string[];
35
+ }[];
36
+ /** The most this delegation and everything under it may spend, in micro-cents. */
37
+ capMicrocents: number;
38
+ /** At most 24 hours, and never past the signer's own delegation. */
39
+ ttlSeconds: number;
40
+ /** false: the worker may not delegate on. */
41
+ allowFurtherDelegation?: boolean;
42
+ /**
43
+ * The gateway's issuer (receipts' `iss`). Defaults to the gateway origin, which is
44
+ * the issuer unless the gateway is reached through another address.
45
+ */
46
+ audience?: string;
47
+ }
19
48
  export declare class PassControl {
20
49
  private readonly gateway;
21
50
  private readonly gatewayOrigin;
@@ -23,6 +52,8 @@ export declare class PassControl {
23
52
  private readonly secret;
24
53
  private readonly skewMs;
25
54
  private readonly transport;
55
+ /** Set only on a worker's client: its chain, sent to /api/auth/delegated. */
56
+ private delegationChain;
26
57
  private cached;
27
58
  private inflight;
28
59
  constructor(opts: PassControlOptions);
@@ -33,6 +64,21 @@ export declare class PassControl {
33
64
  getVisa(): Promise<string>;
34
65
  /** Drop the cached visa so the next getVisa() re-mints. */
35
66
  invalidate(): void;
67
+ /**
68
+ * A client for a WORKER holding a delegation (Bet D). Its calls are refused past the
69
+ * delegation's scope, cap or expiry, and the agent's kill switch and suspension stop
70
+ * it too. Its receipts name the worker, never the agent's passport.
71
+ */
72
+ static fromDelegation(opts: PassControlDelegationOptions): PassControl;
73
+ /**
74
+ * Hand a worker a narrower slice of this client's authority: signed here, offline,
75
+ * by this client's key (the agent's passport, or a worker's own key one level down).
76
+ * Returns the chain to give the worker, root first.
77
+ */
78
+ delegate(opts: DelegateOptions): {
79
+ token: string;
80
+ chain: string[];
81
+ };
36
82
  /** A `fetch` that injects the visa and refreshes it transparently. Pass this as
37
83
  * the `fetch` option to the OpenAI/Anthropic SDK. Retries once on a 401 (the
38
84
  * visa was rejected/expired) after forcing a re-mint. */
@@ -15,6 +15,7 @@
15
15
  // an end-user browser bundle even though the underlying Web APIs are portable.
16
16
  import { ed25519 } from "@noble/curves/ed25519";
17
17
  import { requireGatewayOrigin } from "./gateway.js";
18
+ import { createDelegationLink } from "../cli/delegation.mjs";
18
19
  // --- base64url over raw bytes (no Buffer dependency; works everywhere) -------
19
20
  function bytesToB64url(bytes) {
20
21
  let bin = "";
@@ -73,6 +74,8 @@ export class PassControl {
73
74
  secret;
74
75
  skewMs;
75
76
  transport;
77
+ /** Set only on a worker's client: its chain, sent to /api/auth/delegated. */
78
+ delegationChain = null;
76
79
  cached = null;
77
80
  inflight = null;
78
81
  constructor(opts) {
@@ -103,10 +106,12 @@ export class PassControl {
103
106
  const payloadBytes = new TextEncoder().encode(JSON.stringify(payloadObj));
104
107
  const payload = bytesToB64url(payloadBytes);
105
108
  const signature = bytesToB64url(ed25519.sign(payloadBytes, this.secret));
106
- const res = await this.transport(`${this.gateway}/api/auth/challenge`, {
109
+ // A worker exchanges its chain, signing the challenge with its OWN key: the
110
+ // delegation token alone does nothing at the gateway.
111
+ const res = await this.transport(`${this.gateway}/api/auth/${this.delegationChain ? "delegated" : "challenge"}`, {
107
112
  method: "POST",
108
113
  headers: { "content-type": "application/json" },
109
- body: JSON.stringify({ payload, signature }),
114
+ body: JSON.stringify(this.delegationChain ? { payload, signature, chain: this.delegationChain } : { payload, signature }),
110
115
  });
111
116
  if (!res.ok) {
112
117
  const detail = await res.text().catch(() => "");
@@ -139,6 +144,46 @@ export class PassControl {
139
144
  invalidate() {
140
145
  this.cached = null;
141
146
  }
147
+ /**
148
+ * A client for a WORKER holding a delegation (Bet D). Its calls are refused past the
149
+ * delegation's scope, cap or expiry, and the agent's kill switch and suspension stop
150
+ * it too. Its receipts name the worker, never the agent's passport.
151
+ */
152
+ static fromDelegation(opts) {
153
+ if (!Array.isArray(opts.chain) || opts.chain.length < 1) {
154
+ throw new Error("PassControl: fromDelegation needs the chain the worker was handed.");
155
+ }
156
+ const priv = b64urlToBytes(opts.workerPrivateKey);
157
+ if (priv.length !== 32)
158
+ throw new Error("PassControl: workerPrivateKey must encode 32 bytes.");
159
+ const client = new PassControl({
160
+ gateway: opts.gateway,
161
+ passportId: bytesToB64url(ed25519.getPublicKey(priv)),
162
+ passportSecret: opts.workerPrivateKey,
163
+ ...(opts.refreshSkewSeconds !== undefined ? { refreshSkewSeconds: opts.refreshSkewSeconds } : {}),
164
+ ...(opts.fetch ? { fetch: opts.fetch } : {}),
165
+ });
166
+ client.delegationChain = [...opts.chain];
167
+ return client;
168
+ }
169
+ /**
170
+ * Hand a worker a narrower slice of this client's authority: signed here, offline,
171
+ * by this client's key (the agent's passport, or a worker's own key one level down).
172
+ * Returns the chain to give the worker, root first.
173
+ */
174
+ delegate(opts) {
175
+ const token = createDelegationLink({
176
+ signerPrivateKey: bytesToB64url(this.secret),
177
+ audience: opts.audience ?? this.gatewayOrigin,
178
+ workerPublicKey: opts.workerPublicKey,
179
+ scope: opts.scope,
180
+ capMicrocents: opts.capMicrocents,
181
+ ttlSeconds: opts.ttlSeconds,
182
+ ...(opts.allowFurtherDelegation !== undefined ? { allowFurtherDelegation: opts.allowFurtherDelegation } : {}),
183
+ ...(this.delegationChain ? { parentChain: this.delegationChain } : {}),
184
+ });
185
+ return { token, chain: [...(this.delegationChain ?? []), token] };
186
+ }
142
187
  /** A `fetch` that injects the visa and refreshes it transparently. Pass this as
143
188
  * the `fetch` option to the OpenAI/Anthropic SDK. Retries once on a 401 (the
144
189
  * visa was rejected/expired) after forcing a re-mint. */
package/sdk/verify.d.ts CHANGED
@@ -36,6 +36,13 @@ export interface ReceiptClaims {
36
36
  use: string;
37
37
  } | {
38
38
  kind: "passport_proof_per_request";
39
+ } | {
40
+ kind: "delegated";
41
+ act: string;
42
+ dlg: string;
43
+ dep: number;
44
+ ch: string;
45
+ prf?: true;
39
46
  };
40
47
  prov: string;
41
48
  mdl: string | null;