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

/home/user/app/src:
auth
index.ts

/home/user/app/src/auth:
crypto.ts
errors.ts
types.ts
verify.ts

/home/user/app/test:
smoke.test.ts
---
/**
 * Typed error for unexpected, non-token conditions in the verifier (for example
 * a context that names a `kid` whose secret is absent in an unrecoverable way).
 * Provided complete.
 *
 * Ordinary verification *rejections* are NOT errors: `verify` returns a
 * `{ valid: false, reason }` result for those. `AuthError` is reserved for
 * misuse / configuration faults a caller may choose to throw on.
 */
export type AuthErrorCode =
  /** The verification context is internally unusable. */
  | "bad_context";

export class AuthError extends Error {
  readonly code: AuthErrorCode;

  constructor(code: AuthErrorCode, message: string) {
    super(message);
    this.name = "AuthError";
    this.code = code;
    Object.setPrototypeOf(this, AuthError.prototype);
  }
}

1	import { describe, expect, it } from "vitest";
2	import {
3	  hmacSha256,
4	  base64urlEncode,
5	  base64urlDecode,
6	  timingSafeEqual,
7	} from "../src/auth/crypto.js";
8	import { AuthError } from "../src/auth/errors.js";
9	
10	/**
11	 * Smoke tests for the *provided* surface only , the crypto/encoding helpers and
12	 * the typed error. They do not exercise `verify` (still a stub), so they pass in
13	 * the shipped project and the type-check stays green. The behavioural suite is
14	 * added at grading time.
15	 */
16	describe("provided crypto/encoding surface", () => {
17	  it("base64url round-trips arbitrary bytes (unpadded, URL-safe)", () => {
18	    const bytes = new Uint8Array([0, 1, 2, 250, 251, 252, 253, 254, 255]);
19	    const enc = base64urlEncode(bytes);
20	    expect(enc).not.toMatch(/[+/=]/); // URL-safe, unpadded
21	    expect(Array.from(base64urlDecode(enc))).toEqual(Array.from(bytes));
22	  });
23	
24	  it("base64url decodes a known vector and rejects non-alphabet input", () => {
25	    // "hello" -> aGVsbG8 (unpadded base64url)
26	    expect(base64urlEncode(new Uint8Array(Buffer.from("hello", "utf8")))).toBe("aGVsbG8");
27	    expect(Buffer.from(base64urlDecode("aGVsbG8")).toString("utf8")).toBe("hello");
28	    expect(() => base64urlDecode("aGVsbG8=")).toThrow(RangeError); // padding rejected
29	    expect(() => base64urlDecode("a+b/")).toThrow(RangeError); // standard-base64 chars rejected
30	    expect(Array.from(base64urlDecode(""))).toEqual([]); // empty is valid
31	  });
32	
33	  it("hmacSha256 is deterministic and matches a known vector", () => {
34	    // RFC-style check: HMAC-SHA256(key="key", msg="The quick brown fox jumps over the lazy dog")
35	    // hex = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
36	    const hex = Buffer.from(
37	      base64urlDecode(hmacSha256("key", "The quick brown fox jumps over the lazy dog")),
38	    ).toString("hex");
39	    expect(hex).toBe("f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8");
40	    // Determinism.
41	    expect(hmacSha256("s", "m")).toBe(hmacSha256("s", "m"));
42	    // Different secret or message -> different tag.
43	    expect(hmacSha256("s", "m")).not.toBe(hmacSha256("s2", "m"));
44	    expect(hmacSha256("s", "m")).not.toBe(hmacSha256("s", "m2"));
45	  });
46	
47	  it("timingSafeEqual matches equal strings and rejects unequal/different-length", () => {
48	    expect(timingSafeEqual("abc", "abc")).toBe(true);
49	    expect(timingSafeEqual("abc", "abd")).toBe(false);
50	    expect(timingSafeEqual("abc", "abcd")).toBe(false);
51	    expect(timingSafeEqual("", "")).toBe(true);
52	  });
53	
54	  it("AuthError carries a stable code and is an Error", () => {
55	    const err = new AuthError("bad_context", "boom");
56	    expect(err).toBeInstanceOf(Error);
57	    expect(err).toBeInstanceOf(AuthError);
58	    expect(err.code).toBe("bad_context");
59	    expect(err.name).toBe("AuthError");
60	    expect(err.message).toBe("boom");
61	  });
62	});
63

{
  "name": "session-token-verify",
  "version": "0.1.0",
  "private": true,
  "description": "STV/1 session-token verifier (HMAC-SHA256, base64url) for service-to-service auth.",
  "type": "module",
  "engines": {
    "node": ">=20"
  },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "typecheck": "tsc -p tsconfig.json --noEmit",
    "test": "vitest run",
    "test:watch": "vitest"
  },
  "devDependencies": {
    "@types/node": "20.14.10",
    "typescript": "5.5.3",
    "vitest": "1.6.0"
  }
}
---TSCONFIG---
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022"],
    "types": ["node"],
    "rootDir": ".",
    "outDir": "dist",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": false,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "verbatimModuleSyntax": false
  },
  "include": ["src", "test"],
  "exclude": ["node_modules", "dist"]
}
---INDEX---
/**
 * Public surface of the STV/1 session-token verifier.
 */
export { verify } from "./auth/verify.js";
export {
  hmacSha256,
  base64urlEncode,
  base64urlDecode,
  timingSafeEqual,
} from "./auth/crypto.js";
export { AuthError } from "./auth/errors.js";
export type { AuthErrorCode } from "./auth/errors.js";
export type {
  VerifyContext,
  VerifyResult,
  VerifyOk,
  VerifyFail,
  Reason,
  StvHeader,
  StvPayload,
} from "./auth/types.js";

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===

> 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:49:18
   Duration  313ms (transform 64ms, setup 0ms, collect 61ms, tests 5ms, environment 0ms, prepare 104ms)

npm WARN exec The following package was not found and will be installed: tsx@4.22.4

node:internal/process/esm_loader:40
      internalBinding('errors').triggerUncaughtException(
                                ^
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/tmp/src/auth/crypto.ts' imported from /tmp/chk.mjs
Did you mean to import ../../home/user/app/src/auth/crypto.ts?
    at new NodeError (node:internal/errors:406:5)
    at finalizeResolution (node:internal/modules/esm/resolve:233:11)
    at moduleResolve (node:internal/modules/esm/resolve:845:10)
    at defaultResolve (node:internal/modules/esm/resolve:1043:11)
    at nextResolve (node:internal/modules/esm/hooks:833:28)
    at resolveBase (file:///home/user/.npm/_npx/fd45a72a545557e9/node_modules/tsx/dist/register-CqMfTiWi.mjs:2:8141)
    at resolveDirectory (file:///home/user/.npm/_npx/fd45a72a545557e9/node_modules/tsx/dist/register-CqMfTiWi.mjs:2:9227)
    at resolveTsPaths (file:///home/user/.npm/_npx/fd45a72a545557e9/node_modules/tsx/dist/register-CqMfTiWi.mjs:2:10757)
    at resolve2 (file:///home/user/.npm/_npx/fd45a72a545557e9/node_modules/tsx/dist/register-CqMfTiWi.mjs:2:11938)
    at nextResolve (node:internal/modules/esm/hooks:833:28) {
  url: 'file:///tmp/src/auth/crypto.ts',
  code: 'ERR_MODULE_NOT_FOUND'
}

Node.js v20.9.0

valid: {"valid":true,"sub":"u1","scopes":["write"]}
expired: expired
nyv: not_yet_valid
aud wrong: wrong_audience
revoked ver0: revoked
revoked low: revoked
insuff: insufficient_scope
scope ok: {"valid":true,"sub":"u1","scopes":["write"]}
badsig: bad_signature
malformed segs: malformed
malformed b64: malformed
unknown kid: malformed
empty scope+scopes: []
only scope: {"valid":false,"reason":"bad_signature"}

only scope: {"valid":true,"sub":"u","scopes":["a","b"]}
only scopes: {"valid":true,"sub":"u","scopes":["x","y"]}
neither: {"valid":true,"sub":"u","scopes":[]}
aud prefix exact: true
lifetime exact now==iat+exp: true
nbf skew edge now==nbf-30: true