session-token-verify

1	# Ticket: Implement `verify` for STV/1 session tokens
2	
3	## Context
4	
5	`session-token-verify` is the library every backend service uses to authenticate
6	incoming callers. Clients present an **STV/1** bearer token; a service hands the
7	token plus a verification context to this library and gets back either the
8	authenticated subject (with its effective scopes) or a reason the token was
9	rejected (TypeScript, Node 20).
10	
11	The crypto and encoding primitives (HMAC-SHA256, base64url, constant-time
12	compare), the typed `AuthError`, and all the request/response types are already
13	in place. **Only the verifier itself , `verify` , is unimplemented**, so no
14	service can authenticate anyone yet.
15	
16	## Your task
17	
18	Implement the function in:
19	
20	    src/auth/verify.ts   ->   verify(token: string, ctx: VerifyContext): VerifyResult
21	
22	The full contract is written as JSDoc directly above the stub in that file , it
23	is the spec; the summary below repeats it.
24	
25	## The contract
26	
27	### Token shape
28	
29	An STV/1 token is three base64url segments joined by dots: `header.payload.sig`.
30	`header` decodes to JSON `{ alg, kid }`. `payload` decodes to a JSON object of
31	claims; the claim names are `sub`, `iat`, `exp`, `nbf`, `aud`, `scope`,
32	`scopes`, and `ver`, and a payload may also carry other claims.
33	
34	### Algorithm
35	
36	`alg` must equal `"HS256"`; any other value is not accepted.
37	
38	### Signature
39	
40	Let `secret = ctx.keys[kid]`. Form the **canonical** string from the payload:
41	take every key present in the payload object, sort the keys in ascending
42	(code-unit) order, render each key as `key=value` where `value` is the
43	`JSON.stringify` of that claim's value, and join the pairs with `&`. For example
44	a payload `{ sub: "u1", iat: 1000, exp: 3600, aud: ["a"] }` has canonical string
45	
46	    aud=["a"]&exp=3600&iat=1000&sub="u1"
47	
48	The expected signature is `base64url(HMAC-SHA256(secret, canonical))` and must
49	equal the token's `sig` segment.
50	
51	### Time
52	
53	`iat` and `exp` are seconds. The token is within its lifetime iff
54	`ctx.now <= iat + exp`. `nbf` is absolute epoch seconds; the token has reached
55	its start iff `ctx.now >= nbf - SKEW`, where `SKEW` is `30`. The lifetime bound
56	takes no leeway.
57	
58	### Audience
59	
60	`aud` is an array of strings. `ctx.audience` is accepted iff some entry of `aud`
61	is a prefix of `ctx.audience`, compared case-sensitively (an entry equal to
62	`ctx.audience` counts as a prefix of it).
63	
64	### Scopes
65	
66	The effective scopes are the intersection of `scope` (split on single spaces,
67	discarding empty tokens) and `scopes` when both claims are present; whichever one is present when only one is;
68	and the empty set when neither is. A claim counts as present whenever its key
69	exists (an empty or whitespace-only value is present but contributes no tokens, so
70	e.g. an empty `scope` alongside a `scopes` array yields the empty intersection).
71	The effective scopes are de-duplicated. When `ctx.requiredScopes` is present and
72	non-empty, every entry in it must appear in the effective scopes.
73	
74	### Version
75	
76	`ver` must be present and satisfy `ver >= ctx.minVer`. A `ver` of `0` is never
77	accepted.
78	
79	### Result and reason precedence
80	
81	On success return `{ valid: true, sub, scopes }`, where `scopes` is the effective
82	scope set. On rejection return `{ valid: false, reason }`. A token may break more
83	than one rule; return the first reason that applies in this order:
84	
85	    malformed > bad_signature > expired > not_yet_valid > wrong_audience >
86	    revoked > insufficient_scope
87	
88	`malformed` covers a token whose structure cannot be read or whose required
89	claims are absent: not exactly three segments, a segment that is not valid
90	base64url, a header or payload that is not JSON of the expected shape, an `alg`
91	other than `"HS256"`, a `kid` with no entry in `ctx.keys`, or a missing `sub`,
92	`iat`, `exp`, `nbf`, `aud`, or `ver`. `expired` is the lifetime bound failing;
93	`not_yet_valid` is the start bound failing; `wrong_audience` is the audience rule
94	failing; `revoked` is the version rule failing; `insufficient_scope` is a
95	required scope absent from the effective set.
96	
97	## Definition of done
98	
99	- `npm run typecheck` is clean.
100	- `npm test` passes the full suite in `test/` , the behavioural tests plus a
101	  differential fuzz suite that checks the verifier against an independent model.
102	- Implement the feature within `verify` (and any private helpers you add in
103	  `src/auth/`). Do not modify the provided crypto, types, or errors modules, or
104	  the test files.
105	
106	## Running locally
107	
108	```bash
109	npm install      # already done in the provided environment
110	npm run typecheck
111	npm test
112	```
113

1	import { hmacSha256, base64urlDecode, base64urlEncode, timingSafeEqual } from "./crypto.js";
2	import type { VerifyContext, VerifyResult } from "./types.js";
3	
4	/**
5	 * Verify an STV/1 session token.
6	 *
7	 * A token is three base64url segments joined by dots: `header.payload.sig`.
8	 * `header` decodes to JSON `{ alg, kid }`; `payload` decodes to a JSON object of
9	 * claims (`sub, iat, exp, nbf, aud, scope, scopes, ver`, plus any others).
10	 *
11	 * On success return `{ valid: true, sub, scopes }` where `scopes` is the
12	 * effective scope set (see below). On rejection return `{ valid: false, reason }`
13	 * with the single governing `reason`.
14	 *
15	 * ## Algorithm
16	 *
17	 * `alg` must equal `"HS256"`; any other value is not accepted.
18	 *
19	 * ## Signature
20	 *
21	 * Let `secret` be `ctx.keys[kid]`. Build the canonical string from the payload
22	 * claims: take every key present in the payload object, sort the keys in
23	 * ascending (code-unit) order, render each as `key=value` where `value` is the
24	 * `JSON.stringify` of that claim's value, and join the pairs with `&`. The
25	 * expected signature is `base64url(HMAC-SHA256(secret, canonical))`; it must
26	 * equal `sig`.
27	 *
28	 * ## Time
29	 *
30	 * `iat` and `exp` are seconds; the token is within its lifetime iff
31	 * `ctx.now <= iat + exp`. `nbf` is absolute epoch seconds; the token has reached
32	 * its start iff `ctx.now >= nbf - SKEW`, where `SKEW` is 30. The lifetime bound
33	 * takes no leeway.
34	 *
35	 * ## Audience
36	 *
37	 * `aud` is an array of strings. The context audience `ctx.audience` is accepted
38	 * iff some entry of `aud` is a prefix of `ctx.audience` (case-sensitive; an
39	 * entry equal to `ctx.audience` is a prefix of it).
40	 *
41	 * ## Scopes
42	 *
43	 * The effective scopes are: the intersection of `scope` (split on single spaces,
44	 * discarding empty tokens) and `scopes` when both claims are present; whichever one
45	 * is; the empty set when neither is. A claim counts as present whenever its key
46	 * exists (an empty/whitespace value is present but contributes no tokens, so an
47	 * empty `scope` with a `scopes` array yields the empty intersection); the
48	 * effective scopes are de-duplicated. When `ctx.requiredScopes` is present and
49	 * non-empty, every required scope must be in the effective set.
50	 *
51	 * ## Version
52	 *
53	 * `ver` must be present and satisfy `ver >= ctx.minVer`. A `ver` of `0` is never
54	 * accepted.
55	 *
56	 * ## Reasons
57	 *
58	 * A token may break more than one rule; return the first reason that applies in
59	 * this order:
60	 *
61	 *   malformed > bad_signature > expired > not_yet_valid > wrong_audience >
62	 *   revoked > insufficient_scope
63	 *
64	 * `malformed` covers a token whose structure cannot be read or whose required
65	 * claims are absent: not exactly three segments, a segment that is not valid
66	 * base64url, header or payload that is not JSON of the expected shape, an `alg`
67	 * other than `"HS256"`, an unknown `kid`, or a missing `sub`, `iat`, `exp`,
68	 * `nbf`, `aud`, or `ver`. `revoked` is a version that fails the version rule.
69	 * `insufficient_scope` is a required scope absent from the effective set.
70	 */
71	export function verify(token: string, ctx: VerifyContext): VerifyResult {
72	  // Referenced so the throwing stub still type-checks under strict settings.
73	  void token;
74	  void ctx;
75	  void hmacSha256;
76	  void base64urlDecode;
77	  void base64urlEncode;
78	  void timingSafeEqual;
79	
80	  // TODO(stv): decode the three segments, validate the header, recompute the
81	  // canonical signing string from the payload claims and check the signature,
82	  // then apply the time / audience / scope / version rules and return either the
83	  // authenticated subject with its effective scopes or the first failing reason
84	  // in the precedence order documented above.
85	  //
86	  // This stub throws so the module is wired but non-functional; the behavioural
87	  // suite must fail until the real implementation replaces this body.
88	  throw new Error("verify not implemented");
89	}
90

1	/**
2	 * Shared types for the session-token verifier. Provided complete.
3	 *
4	 * These describe the *shape* of the input and output only. The STV/1
5	 * verification rules live in the JSDoc above `verify` in `verify.ts`.
6	 */
7	
8	/**
9	 * The decoded STV/1 header. `alg` names the signing algorithm; `kid` selects the
10	 * secret from `VerifyContext.keys`.
11	 */
12	export interface StvHeader {
13	  alg: string;
14	  kid: string;
15	}
16	
17	/**
18	 * The decoded STV/1 payload. All fields are optional at the type level because a
19	 * token may omit any of them; the verifier decides which are required and how
20	 * each is interpreted. A `JSON.parse` of the payload segment yields this shape.
21	 */
22	export interface StvPayload {
23	  /** Subject (principal) identifier. */
24	  sub?: string;
25	  /** Issued-at, absolute epoch seconds. */
26	  iat?: number;
27	  /** Lifetime in seconds measured from `iat`. */
28	  exp?: number;
29	  /** Not-before, absolute epoch seconds. */
30	  nbf?: number;
31	  /** Audience entries. */
32	  aud?: string[];
33	  /** Space-delimited scope grant. */
34	  scope?: string;
35	  /** Scope grant as an array. */
36	  scopes?: string[];
37	  /** Token version, used for revocation. */
38	  ver?: number;
39	  /** Any additional claims a token may carry (covered by the signature). */
40	  [k: string]: unknown;
41	}
42	
43	/**
44	 * Inputs the caller supplies to a verification, beyond the token itself.
45	 */
46	export interface VerifyContext {
47	  /** Current time, absolute epoch seconds. */
48	  now: number;
49	  /** The audience this verification is being performed for. */
50	  audience: string;
51	  /** The minimum acceptable token version. */
52	  minVer: number;
53	  /** Map from `kid` to that key's shared secret (UTF-8). */
54	  keys: Record<string, string>;
55	  /**
56	   * Scopes the caller demands the token carry. When present and non-empty, the
57	   * token's effective scopes must include every entry. When absent or empty, no
58	   * scope is demanded.
59	   */
60	  requiredScopes?: string[];
61	}
62	
63	/**
64	 * Why a token was rejected. The verifier returns exactly one reason, chosen by a
65	 * fixed precedence when more than one rule is violated.
66	 */
67	export type Reason =
68	  | "malformed"
69	  | "bad_signature"
70	  | "expired"
71	  | "not_yet_valid"
72	  | "wrong_audience"
73	  | "revoked"
74	  | "insufficient_scope";
75	
76	/** A successful verification: the authenticated subject and effective scopes. */
77	export interface VerifyOk {
78	  valid: true;
79	  sub: string;
80	  scopes: string[];
81	}
82	
83	/** A rejected verification, carrying the single governing reason. */
84	export interface VerifyFail {
85	  valid: false;
86	  reason: Reason;
87	}
88	
89	/** Result of `verify`: success carries `sub` + scopes; failure carries a reason. */
90	export type VerifyResult = VerifyOk | VerifyFail;
91

1	/**
2	 * Cryptographic and encoding primitives for the session-token verifier.
3	 * Provided complete , these are ordinary, well-tested building blocks and say
4	 * nothing about the STV/1 verification rules themselves.
5	 *
6	 * All base64url here is the unpadded URL-safe alphabet (RFC 4648 §5 without `=`
7	 * padding): `+` -> `-`, `/` -> `_`, trailing `=` stripped.
8	 */
9	import { createHmac, timingSafeEqual as nodeTimingSafeEqual } from "node:crypto";
10	
11	/** Encode raw bytes as unpadded base64url. */
12	export function base64urlEncode(bytes: Uint8Array): string {
13	  return Buffer.from(bytes).toString("base64url");
14	}
15	
16	/**
17	 * Decode an unpadded base64url string to raw bytes.
18	 *
19	 * Strict: rejects any character outside the URL-safe alphabet (including `=`
20	 * padding and standard-base64 `+`/`/`) by throwing `RangeError`. A valid empty
21	 * string decodes to an empty buffer.
22	 */
23	export function base64urlDecode(s: string): Uint8Array {
24	  if (!/^[A-Za-z0-9_-]*$/.test(s)) {
25	    throw new RangeError("invalid base64url");
26	  }
27	  // Buffer's base64url decoder is lenient about length; the regex above already
28	  // guarantees the alphabet, so a clean round-trip check catches malformed input
29	  // (e.g. a stray length that cannot represent whole bytes).
30	  const out = Buffer.from(s, "base64url");
31	  if (out.toString("base64url") !== s) {
32	    throw new RangeError("invalid base64url");
33	  }
34	  return new Uint8Array(out);
35	}
36	
37	/**
38	 * HMAC-SHA256 of the UTF-8 bytes of `msg` under `secret`, returned as unpadded
39	 * base64url. `secret` is interpreted as UTF-8.
40	 */
41	export function hmacSha256(secret: string, msg: string): string {
42	  return createHmac("sha256", Buffer.from(secret, "utf8"))
43	    .update(Buffer.from(msg, "utf8"))
44	    .digest("base64url");
45	}
46	
47	/**
48	 * Constant-time string comparison. Returns `true` iff `a` and `b` are equal.
49	 * Strings of differing length compare as unequal (in constant time relative to
50	 * the shorter input). Both are compared by their UTF-8 byte representation.
51	 */
52	export function timingSafeEqual(a: string, b: string): boolean {
53	  const ab = Buffer.from(a, "utf8");
54	  const bb = Buffer.from(b, "utf8");
55	  if (ab.length !== bb.length) {
56	    // Still touch nodeTimingSafeEqual against a same-length buffer so callers
57	    // cannot trivially distinguish the length-mismatch path by timing alone.
58	    nodeTimingSafeEqual(ab, ab);
59	    return false;
60	  }
61	  return nodeTimingSafeEqual(ab, bb);
62	}
63

1	/**
2	 * Typed error for unexpected, non-token conditions in the verifier (for example
3	 * a context that names a `kid` whose secret is absent in an unrecoverable way).
4	 * Provided complete.
5	 *
6	 * Ordinary verification *rejections* are NOT errors: `verify` returns a
7	 * `{ valid: false, reason }` result for those. `AuthError` is reserved for
8	 * misuse / configuration faults a caller may choose to throw on.
9	 */
10	export type AuthErrorCode =
11	  /** The verification context is internally unusable. */
12	  | "bad_context";
13	
14	export class AuthError extends Error {
15	  readonly code: AuthErrorCode;
16	
17	  constructor(code: AuthErrorCode, message: string) {
18	    super(message);
19	    this.name = "AuthError";
20	    this.code = code;
21	    Object.setPrototypeOf(this, AuthError.prototype);
22	  }
23	}
24

The file /home/user/app/src/auth/verify.ts has been updated successfully. (file state is current in your context , no need to Read it back)

The file /home/user/app/src/auth/verify.ts has been updated successfully. (file state is current in your context , no need to Read it back)

The file /home/user/app/src/auth/verify.ts has been updated successfully. (file state is current in your context , no need to Read it back)

> session-token-verify@0.1.0 typecheck
> tsc -p tsconfig.json --noEmit

> session-token-verify@0.1.0 test
> vitest run


 RUN  v1.6.0 /home/user/app

 ✓ test/smoke.test.ts  (5 tests) 5ms

 Test Files  1 passed (1)
      Tests  5 passed (5)
   Start at  19:37:21
   Duration  316ms (transform 70ms, setup 0ms, collect 59ms, tests 5ms, environment 0ms, prepare 110ms)

71	const SKEW = 30;
72	
73	/** Reject helper. */
74	function fail(reason: Reason): VerifyResult {
75	  return { valid: false, reason };
76	}
77	
78	/** Decode a base64url segment to its UTF-8 string, or `null` if not base64url. */
79	function decodeSegment(seg: string): string | null {
80	  try {
81	    return Buffer.from(base64urlDecode(seg)).toString("utf8");
82	  } catch {
83	    return null;
84	  }
85	}
86	
87	/** True for a non-null, non-array plain object. */
88	function isObject(v: unknown): v is Record<string, unknown> {
89	  return typeof v === "object" && v !== null && !Array.isArray(v);
90	}
91	
92	/**
93	 * Build the canonical signing string: every key present in the payload, sorted
94	 * in ascending code-unit order, rendered as `key=JSON.stringify(value)` and
95	 * joined with `&`.
96	 */
97	function canonicalString(payload: Record<string, unknown>): string {
98	  return Object.keys(payload)
99	    .sort()
100	    .map((key) => `${key}=${JSON.stringify(payload[key])}`)
101	    .join("&");
102	}
103	
104	export function verify(token: string, ctx: VerifyContext): VerifyResult {
105	  void base64urlEncode;
106	
107	  // --- structure: exactly three segments ---
108	  const segments = token.split(".");
109	  if (segments.length !== 3) return fail("malformed");
110	  const [headerSeg, payloadSeg, sigSeg] = segments;
111	
112	  // --- every segment must be valid base64url ---
113	  const headerJson = decodeSegment(headerSeg);
114	  const payloadJson = decodeSegment(payloadSeg);
115	  if (headerJson === null || payloadJson === null || decodeSegment(sigSeg) === null) {
116	    return fail("malformed");
117	  }
118	
119	  // --- header must be JSON of the expected shape ---
120	  let header: unknown;
121	  try {
122	    header = JSON.parse(headerJson);
123	  } catch {
124	    return fail("malformed");
125	  }
126	  if (!isObject(header)) return fail("malformed");
127	  if (header.alg !== "HS256") return fail("malformed");
128	  const kid = header.kid;
129	  if (typeof kid !== "string") return fail("malformed");
130	  const secret = ctx.keys[kid];
131	  if (typeof secret !== "string") return fail("malformed");
132	
133	  // --- payload must be JSON of the expected shape ---
134	  let payload: unknown;
135	  try {
136	    payload = JSON.parse(payloadJson);
137	  } catch {
138	    return fail("malformed");
139	  }
140	  if (!isObject(payload)) return fail("malformed");
141	
142	  // --- required claims must be present ---
143	  for (const claim of ["sub", "iat", "exp", "nbf", "aud", "ver"]) {
144	    if (!(claim in payload)) return fail("malformed");
145	  }
146	
147	  // --- signature ---
148	  const expectedSig = hmacSha256(secret, canonicalString(payload));
149	  if (!timingSafeEqual(expectedSig, sigSeg)) return fail("bad_signature");
150	
151	  // --- time: lifetime bound (no leeway) ---
152	  const iat = payload.iat as number;
153	  const exp = payload.exp as number;
154	  if (!(ctx.now <= iat + exp)) return fail("expired");
155	
156	  // --- time: start bound (with skew) ---
157	  const nbf = payload.nbf as number;
158	  if (!(ctx.now >= nbf - SKEW)) return fail("not_yet_valid");
159	
160	  // --- audience: some entry of aud is a prefix of ctx.audience ---
161	  const aud = payload.aud;
162	  const audOk =
163	    Array.isArray(aud) &&
164	    aud.some((entry) => typeof entry === "string" && ctx.audience.startsWith(entry));
165	  if (!audOk) return fail("wrong_audience");
166	
167	  // --- version ---
168	  const ver = payload.ver;
169	  if (typeof ver !== "number" || ver === 0 || ver < ctx.minVer) return fail("revoked");
170	
171	  // --- scopes ---
172	  const hasScope = "scope" in payload;
173	  const hasScopes = "scopes" in payload;
174	  const scopeTokens =
175	    typeof payload.scope === "string"
176	      ? payload.scope.split(" ").filter((t) => t.length > 0)
177	      : [];
178	  const scopesArr = Array.isArray(payload.scopes)
179	    ? payload.scopes.filter((s): s is string => typeof s === "string")
180	    : [];
181	
182	  let effective: string[];
183	  if (hasScope && hasScopes) {
184	    const inScopes = new Set(scopesArr);
185	    effective = scopeTokens.filter((t) => inScopes.has(t));
186	  } else if (hasScope) {
187	    effective = scopeTokens;
188	  } else if (hasScopes) {
189	    effective = scopesArr;
190	  } else {

The file /home/user/app/src/auth/verify.ts has been updated successfully. (file state is current in your context , no need to Read it back)

The file /home/user/app/src/auth/verify.ts has been updated successfully. (file state is current in your context , no need to Read it back)

> session-token-verify@0.1.0 typecheck
> tsc -p tsconfig.json --noEmit

---

 ✓ test/smoke.test.ts  (5 tests) 5ms

 Test Files  1 passed (1)
      Tests  5 passed (5)
   Start at  19:37:53
   Duration  319ms (transform 80ms, setup 0ms, collect 66ms, tests 5ms, environment 0ms, prepare 108ms)