@deliverd/sdk 0.31.0 → 0.33.0

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.
@@ -48,6 +48,10 @@ export interface DecisionTokenClaims {
48
48
  artifact: string | null;
49
49
  iat: number;
50
50
  exp: number;
51
+ /** The Deliverd agent that asked. Absent on tokens issued before it was added. */
52
+ agent?: string | null;
53
+ /** This token's id, for a replay guard. Absent on tokens issued before it was added. */
54
+ jti?: string;
51
55
  }
52
56
 
53
57
  export interface DecisionTokenExpectation {
@@ -59,6 +63,35 @@ export interface DecisionTokenExpectation {
59
63
  destination?: { type: string; id: string } | null;
60
64
  /** The SHA-256 of what you are sending, when the gate named an artifact. */
61
65
  artifactSha256?: string | null;
66
+ /**
67
+ * The Deliverd agent id you expect to have asked. When set, a token another
68
+ * agent earned is refused, and so is one that names no agent.
69
+ */
70
+ agent?: string;
71
+ }
72
+
73
+ /**
74
+ * Refuses a token seen before, so one yes cannot be replayed at your service
75
+ * without a call to Deliverd. `claim` returns false when the id was already
76
+ * claimed; keep each id until `expiresAt` (unix seconds). Back it with Redis
77
+ * (`SET jti 1 NX EXAT exp`) when you run more than one instance.
78
+ */
79
+ export interface ReplayGuard {
80
+ claim(jti: string, expiresAt: number): boolean | Promise<boolean>;
81
+ }
82
+
83
+ /** A replay guard for one process. Ids are dropped once their token has expired. */
84
+ export function memoryReplayGuard(): ReplayGuard {
85
+ const seen = new Map<string, number>();
86
+ return {
87
+ claim(jti, expiresAt) {
88
+ const now = Math.floor(Date.now() / 1000);
89
+ if (seen.size > 10_000) for (const [k, exp] of seen) if (exp < now) seen.delete(k);
90
+ if (seen.has(jti)) return false;
91
+ seen.set(jti, expiresAt);
92
+ return true;
93
+ },
94
+ };
62
95
  }
63
96
 
64
97
  export type DecisionTokenFailure =
@@ -70,7 +103,9 @@ export type DecisionTokenFailure =
70
103
  | "wrong_action"
71
104
  | "input_mismatch"
72
105
  | "destination_mismatch"
73
- | "artifact_mismatch";
106
+ | "artifact_mismatch"
107
+ | "wrong_agent"
108
+ | "replayed";
74
109
 
75
110
  export type DecisionTokenResult =
76
111
  | { ok: true; claims: DecisionTokenClaims }
@@ -139,9 +174,21 @@ export function verifyDecisionToken(
139
174
  if (!d || !sameDestination(d, claims.dest)) return { ok: false, reason: "destination_mismatch" };
140
175
  }
141
176
  if (claims.artifact && expected.artifactSha256 !== claims.artifact) return { ok: false, reason: "artifact_mismatch" };
177
+ if (expected.agent !== undefined && claims.agent !== expected.agent) return { ok: false, reason: "wrong_agent" };
142
178
  return { ok: true, claims };
143
179
  }
144
180
 
181
+ /**
182
+ * Spend a verified token's id with a replay guard. A token with no id (issued
183
+ * before ids were added) cannot be guarded and is refused, so turning a guard
184
+ * on never quietly lets an unguardable token through.
185
+ */
186
+ export async function claimOnce(result: DecisionTokenResult, guard: ReplayGuard | undefined): Promise<DecisionTokenResult> {
187
+ if (!result.ok || !guard) return result;
188
+ if (!result.claims.jti) return { ok: false, reason: "replayed" };
189
+ return (await guard.claim(result.claims.jti, result.claims.exp)) ? result : { ok: false, reason: "replayed" };
190
+ }
191
+
145
192
  /**
146
193
  * `deliverd.decisionTokens`: verification against the deployment this client
147
194
  * talks to. The key comes from that deployment's own well-known address and
@@ -159,11 +206,12 @@ export class DecisionTokens {
159
206
  async verify(
160
207
  token: string | null | undefined,
161
208
  expected: DecisionTokenExpectation,
162
- options: { now?: Date; skewSeconds?: number } = {}
209
+ options: { now?: Date; skewSeconds?: number; replay?: ReplayGuard } = {}
163
210
  ): Promise<DecisionTokenResult> {
164
211
  if (!token) return { ok: false, reason: "missing" };
165
212
  const publicKey = await this.publicKey();
166
- return verifyDecisionToken(token, expected, { publicKey, issuer: new URL(this.baseUrl).origin, ...options });
213
+ const { replay, ...clock } = options;
214
+ return claimOnce(verifyDecisionToken(token, expected, { publicKey, issuer: new URL(this.baseUrl).origin, ...clock }), replay);
167
215
  }
168
216
 
169
217
  private publicKey(): Promise<KeyObject> {
package/src/index.ts CHANGED
@@ -45,6 +45,9 @@ export {
45
45
  DecisionTokens,
46
46
  EVIDENCE_KEY_PATH,
47
47
  verifyDecisionToken,
48
+ claimOnce,
49
+ memoryReplayGuard,
50
+ type ReplayGuard,
48
51
  type DecisionTokenClaims,
49
52
  type DecisionTokenExpectation,
50
53
  type DecisionTokenFailure,
package/src/messages.ts CHANGED
@@ -116,7 +116,7 @@ export const EXPLANATIONS: Record<string, Explanation> = {
116
116
  */
117
117
  agent_not_found: {
118
118
  message: "The agent identity this key acts as is not there any more.",
119
- hint: "Nothing is wrong with the credential — it still authenticates, and what is gone is the identity it speaks as. Recreate the agent under Admin → Agents, or issue a key bound to one that exists. Every call this key makes fails the same way until then.",
119
+ hint: "Nothing is wrong with the credential — it still authenticates, and what is gone is the identity it speaks as. Recreate the agent under Agents → Agents, or issue a key bound to one that exists. Every call this key makes fails the same way until then.",
120
120
  },
121
121
  upload_not_found: {
122
122
  hint: "A publish consumes the bundle it reads, so this is what a *second* publish with the same `uploadId` gets — which means the first one may well have worked. Look at the report before uploading again, or you will publish it twice.",