@data-club/ai-hub-server 0.0.1

package/dist/auth/argon2.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Argon2id helpers.
+ *
+ * One canonical place to declare the OWASP-baseline parameters (`m=19456` KiB
+ * = 19 MiB, `t=2`, `p=1`, 16-byte salt, 32-byte digest) so a future bump is
+ * one constant change rather than hunting through call sites (§8.5).
+ *
+ * The encoded hash is PHC-string format, which embeds m/t/p/salt/digest
+ * inline — `verify` reads them straight from the stored string, and
+ * `needsRehash` compares the embedded params against the current baseline so
+ * we can re-hash on next successful login (the spec calls this "hash
+ * upgrade").
+ *
+ * @see SPECIFICATIONS.md §8.5 — Argon2id parameters + hash upgrade
+ */
+/**
+ * Current Argon2id parameter baseline. Bumping any of these:
+ *
+ * 1. Update this object.
+ * 2. Existing hashes still verify (the encoded hash carries its own params).
+ * 3. On the next successful login `needsRehash` returns true and `hashPassword`
+ *    rewrites the stored hash with the new params.
+ *
+ * @see SPECIFICATIONS.md §8.5
+ */
+export declare const ARGON2_PARAMS: Readonly<{
+    algorithm: 2;
+    /** OWASP baseline as of 2024 — 19 MiB. */
+    memoryCost: 19456;
+    /** Time cost — 2 iterations. */
+    timeCost: 2;
+    /** Parallelism — single lane is fine for password hashing. */
+    parallelism: 1;
+    /** 32-byte digest. */
+    outputLen: 32;
+}>;
+/**
+ * Hashes `password` with the current `ARGON2_PARAMS`. Returns a PHC-string-
+ * format encoded hash safe to store in `user.password_hash`.
+ *
+ * @param password - the plaintext password.
+ * @returns the encoded hash.
+ */
+export declare function hashPassword(password: string): Promise<string>;
+/**
+ * Verifies `password` against `encoded` (a PHC-string-format Argon2id hash
+ * previously written by `hashPassword`).
+ *
+ * Returns `false` for any reason — bad password, malformed hash, wrong
+ * algorithm — without throwing. Callers should treat false as "credentials
+ * do not match" and respond with a generic 401.
+ *
+ * @param encoded - the encoded hash from `user.password_hash`.
+ * @param password - the candidate plaintext password.
+ * @returns `true` if the password is correct.
+ */
+export declare function verifyPassword(encoded: string, password: string): Promise<boolean>;
+/**
+ * Returns `true` if `encoded` was produced with weaker params than the
+ * current `ARGON2_PARAMS` baseline. The spec's hash-upgrade-on-login policy
+ * uses this — on a successful login with `needsRehash(stored) === true`, we
+ * rehash the supplied plaintext and write the new hash back (§8.5).
+ *
+ * Parses the PHC string by hand because `@node-rs/argon2` doesn't expose a
+ * params-only inspector. Format:
+ * `$argon2id$v=19$m=19456,t=2,p=1$<salt-b64>$<hash-b64>`.
+ *
+ * @param encoded - the encoded hash to inspect.
+ * @returns `true` if the hash should be replaced on next successful login.
+ */
+export declare function needsRehash(encoded: string): boolean;
+//# sourceMappingURL=argon2.d.ts.map

package/dist/auth/argon2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argon2.d.ts","sourceRoot":"","sources":["../../src/auth/argon2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa;;IAExB,0CAA0C;;IAE1C,gCAAgC;;IAEhC,8DAA8D;;IAE9D,sBAAsB;;EAEtB,CAAC;AAEH;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAQlB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQpD"}

package/dist/auth/argon2.js

@@ -0,0 +1,145 @@
+/**
+ * Argon2id helpers.
+ *
+ * One canonical place to declare the OWASP-baseline parameters (`m=19456` KiB
+ * = 19 MiB, `t=2`, `p=1`, 16-byte salt, 32-byte digest) so a future bump is
+ * one constant change rather than hunting through call sites (§8.5).
+ *
+ * The encoded hash is PHC-string format, which embeds m/t/p/salt/digest
+ * inline — `verify` reads them straight from the stored string, and
+ * `needsRehash` compares the embedded params against the current baseline so
+ * we can re-hash on next successful login (the spec calls this "hash
+ * upgrade").
+ *
+ * @see SPECIFICATIONS.md §8.5 — Argon2id parameters + hash upgrade
+ */
+import { hash, verify } from "@node-rs/argon2";
+/**
+ * `@node-rs/argon2` exports `Algorithm` as a `const enum` whose values are
+ * compiled away — `verbatimModuleSyntax` (our tsconfig baseline) forbids
+ * referencing those at runtime. We hardcode the numeric tag instead. The
+ * upstream values are stable: `Argon2d = 0, Argon2i = 1, Argon2id = 2`.
+ *
+ * @see https://github.com/napi-rs/node-rs/blob/main/packages/argon2/index.d.ts
+ */
+const ARGON2_ID_ALGORITHM = 2;
+/**
+ * Current Argon2id parameter baseline. Bumping any of these:
+ *
+ * 1. Update this object.
+ * 2. Existing hashes still verify (the encoded hash carries its own params).
+ * 3. On the next successful login `needsRehash` returns true and `hashPassword`
+ *    rewrites the stored hash with the new params.
+ *
+ * @see SPECIFICATIONS.md §8.5
+ */
+export const ARGON2_PARAMS = Object.freeze({
+    algorithm: ARGON2_ID_ALGORITHM,
+    /** OWASP baseline as of 2024 — 19 MiB. */
+    memoryCost: 19456,
+    /** Time cost — 2 iterations. */
+    timeCost: 2,
+    /** Parallelism — single lane is fine for password hashing. */
+    parallelism: 1,
+    /** 32-byte digest. */
+    outputLen: 32,
+});
+/**
+ * Hashes `password` with the current `ARGON2_PARAMS`. Returns a PHC-string-
+ * format encoded hash safe to store in `user.password_hash`.
+ *
+ * @param password - the plaintext password.
+ * @returns the encoded hash.
+ */
+export async function hashPassword(password) {
+    return hash(password, ARGON2_PARAMS);
+}
+/**
+ * Verifies `password` against `encoded` (a PHC-string-format Argon2id hash
+ * previously written by `hashPassword`).
+ *
+ * Returns `false` for any reason — bad password, malformed hash, wrong
+ * algorithm — without throwing. Callers should treat false as "credentials
+ * do not match" and respond with a generic 401.
+ *
+ * @param encoded - the encoded hash from `user.password_hash`.
+ * @param password - the candidate plaintext password.
+ * @returns `true` if the password is correct.
+ */
+export async function verifyPassword(encoded, password) {
+    try {
+        return await verify(encoded, password);
+    }
+    catch {
+        // Malformed hash, wrong algorithm, etc. — don't crash a login attempt
+        // because of stored data integrity issues; just deny.
+        return false;
+    }
+}
+/**
+ * Returns `true` if `encoded` was produced with weaker params than the
+ * current `ARGON2_PARAMS` baseline. The spec's hash-upgrade-on-login policy
+ * uses this — on a successful login with `needsRehash(stored) === true`, we
+ * rehash the supplied plaintext and write the new hash back (§8.5).
+ *
+ * Parses the PHC string by hand because `@node-rs/argon2` doesn't expose a
+ * params-only inspector. Format:
+ * `$argon2id$v=19$m=19456,t=2,p=1$<salt-b64>$<hash-b64>`.
+ *
+ * @param encoded - the encoded hash to inspect.
+ * @returns `true` if the hash should be replaced on next successful login.
+ */
+export function needsRehash(encoded) {
+    const parsed = parseArgon2Hash(encoded);
+    if (!parsed)
+        return true;
+    if (parsed.algorithm !== "argon2id")
+        return true;
+    if (parsed.memoryCost < ARGON2_PARAMS.memoryCost)
+        return true;
+    if (parsed.timeCost < ARGON2_PARAMS.timeCost)
+        return true;
+    if (parsed.parallelism < ARGON2_PARAMS.parallelism)
+        return true;
+    return false;
+}
+/**
+ * Cracks a PHC-formatted Argon2 hash into its component parameters. Returns
+ * `null` on any malformed input.
+ *
+ * @param encoded - the PHC-string-format encoded hash.
+ * @returns the parsed parameters, or `null` if the string isn't a valid hash.
+ */
+function parseArgon2Hash(encoded) {
+    // Format: $argon2id$v=19$m=19456,t=2,p=1$salt$hash
+    const parts = encoded.split("$");
+    if (parts.length < 6)
+        return null;
+    const [, algorithm, , params] = parts;
+    if (!algorithm || !params)
+        return null;
+    const out = {
+        algorithm,
+        memoryCost: 0,
+        timeCost: 0,
+        parallelism: 0,
+    };
+    for (const seg of params.split(",")) {
+        const [k, v] = seg.split("=");
+        if (!k || !v)
+            continue;
+        const n = Number(v);
+        if (!Number.isFinite(n))
+            return null;
+        if (k === "m")
+            out.memoryCost = n;
+        else if (k === "t")
+            out.timeCost = n;
+        else if (k === "p")
+            out.parallelism = n;
+    }
+    if (!out.memoryCost || !out.timeCost || !out.parallelism)
+        return null;
+    return out;
+}
+//# sourceMappingURL=argon2.js.map

package/dist/auth/argon2.js.map

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

package/dist/auth/encryption.d.ts

@@ -0,0 +1,52 @@
+/**
+ * AES-256-GCM helpers for encrypting `admin_setting.letta_api_key_encrypted`
+ * (§6.8). The key (`AI_HUB_ENCRYPTION_KEY`) lives in env only — separating
+ * the key-encrypting key from the encrypted blob is the entire point.
+ *
+ * Output layout (a single Buffer): `<12-byte IV><16-byte auth tag><ciphertext>`.
+ * Reading code slices the same offsets back out before calling `decipher`.
+ *
+ * **Key format:** the env value is parsed as a hex string (64 chars = 32
+ * bytes) or a base64 string (44 chars including `=` padding). Operators with
+ * a stricter preference can pre-decode and pass the bytes through their own
+ * config layer — `parseEncryptionKey` is the single boundary that interprets
+ * the env string.
+ *
+ * @see SPECIFICATIONS.md §6.8 — persistence
+ * @see SPECIFICATIONS.md §12.1 — `AI_HUB_ENCRYPTION_KEY`
+ */
+/**
+ * Encrypts `plaintext` with AES-256-GCM under `key`. Returns
+ * `IV(12) || tag(16) || ciphertext` as a single Buffer.
+ *
+ * @param key - 32-byte encryption key.
+ * @param plaintext - utf-8 string (typically the Letta API key).
+ * @returns the binary blob to store in `admin_setting.letta_api_key_encrypted`.
+ */
+export declare function encryptString(key: Buffer, plaintext: string): Buffer;
+/**
+ * Decrypts a blob produced by `encryptString` back to its utf-8 plaintext.
+ *
+ * Throws on tampering / wrong key — the GCM tag check is the trust gate. The
+ * thrown error is intentionally generic; callers should not surface details
+ * to clients (avoid distinguishing "wrong key" from "corrupted ciphertext"
+ * in user-facing messages).
+ *
+ * @param key - 32-byte encryption key.
+ * @param blob - the binary blob from the DB.
+ * @returns the original utf-8 plaintext.
+ */
+export declare function decryptString(key: Buffer, blob: Buffer): string;
+/**
+ * Parses `AI_HUB_ENCRYPTION_KEY` into a 32-byte Buffer.
+ *
+ * Accepts either a 64-char hex string (`"0a1b…"`, lower or upper case) or a
+ * base64 / base64url string that decodes to exactly 32 bytes. Throws a
+ * clear error otherwise — the operator hits this on first boot and the
+ * message tells them what shape we want.
+ *
+ * @param raw - the raw env value.
+ * @returns the parsed 32-byte key.
+ */
+export declare function parseEncryptionKey(raw: string): Buffer;
+//# sourceMappingURL=encryption.d.ts.map

package/dist/auth/encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../src/auth/encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAaH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAWpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgB/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBtD"}

package/dist/auth/encryption.js

@@ -0,0 +1,98 @@
+/**
+ * AES-256-GCM helpers for encrypting `admin_setting.letta_api_key_encrypted`
+ * (§6.8). The key (`AI_HUB_ENCRYPTION_KEY`) lives in env only — separating
+ * the key-encrypting key from the encrypted blob is the entire point.
+ *
+ * Output layout (a single Buffer): `<12-byte IV><16-byte auth tag><ciphertext>`.
+ * Reading code slices the same offsets back out before calling `decipher`.
+ *
+ * **Key format:** the env value is parsed as a hex string (64 chars = 32
+ * bytes) or a base64 string (44 chars including `=` padding). Operators with
+ * a stricter preference can pre-decode and pass the bytes through their own
+ * config layer — `parseEncryptionKey` is the single boundary that interprets
+ * the env string.
+ *
+ * @see SPECIFICATIONS.md §6.8 — persistence
+ * @see SPECIFICATIONS.md §12.1 — `AI_HUB_ENCRYPTION_KEY`
+ */
+import { createCipheriv, createDecipheriv, randomBytes, } from "node:crypto";
+/** AES-256-GCM uses a 256-bit key (32 bytes) and a 96-bit IV (12 bytes). */
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+/**
+ * Encrypts `plaintext` with AES-256-GCM under `key`. Returns
+ * `IV(12) || tag(16) || ciphertext` as a single Buffer.
+ *
+ * @param key - 32-byte encryption key.
+ * @param plaintext - utf-8 string (typically the Letta API key).
+ * @returns the binary blob to store in `admin_setting.letta_api_key_encrypted`.
+ */
+export function encryptString(key, plaintext) {
+    if (key.length !== KEY_BYTES) {
+        throw new Error(`encryption key must be ${KEY_BYTES} bytes; got ${key.length}`);
+    }
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, ct]);
+}
+/**
+ * Decrypts a blob produced by `encryptString` back to its utf-8 plaintext.
+ *
+ * Throws on tampering / wrong key — the GCM tag check is the trust gate. The
+ * thrown error is intentionally generic; callers should not surface details
+ * to clients (avoid distinguishing "wrong key" from "corrupted ciphertext"
+ * in user-facing messages).
+ *
+ * @param key - 32-byte encryption key.
+ * @param blob - the binary blob from the DB.
+ * @returns the original utf-8 plaintext.
+ */
+export function decryptString(key, blob) {
+    if (key.length !== KEY_BYTES) {
+        throw new Error(`encryption key must be ${KEY_BYTES} bytes; got ${key.length}`);
+    }
+    if (blob.length < IV_BYTES + TAG_BYTES + 1) {
+        throw new Error("ciphertext too short");
+    }
+    const iv = blob.subarray(0, IV_BYTES);
+    const tag = blob.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
+    const ct = blob.subarray(IV_BYTES + TAG_BYTES);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
+    return pt.toString("utf8");
+}
+/**
+ * Parses `AI_HUB_ENCRYPTION_KEY` into a 32-byte Buffer.
+ *
+ * Accepts either a 64-char hex string (`"0a1b…"`, lower or upper case) or a
+ * base64 / base64url string that decodes to exactly 32 bytes. Throws a
+ * clear error otherwise — the operator hits this on first boot and the
+ * message tells them what shape we want.
+ *
+ * @param raw - the raw env value.
+ * @returns the parsed 32-byte key.
+ */
+export function parseEncryptionKey(raw) {
+    const trimmed = raw.trim();
+    if (/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+        return Buffer.from(trimmed, "hex");
+    }
+    // base64 / base64url — Node tolerates both via the "base64" decoder if
+    // the input is base64; we normalize url-safe variants first.
+    const normalized = trimmed.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized + "===".slice((normalized.length + 3) % 4);
+    try {
+        const buf = Buffer.from(padded, "base64");
+        if (buf.length === KEY_BYTES)
+            return buf;
+    }
+    catch {
+        /* fall through to throw below */
+    }
+    throw new Error(`AI_HUB_ENCRYPTION_KEY must be 32 bytes (64 hex chars or base64-encoded); got ${trimmed.length} chars`);
+}
+//# sourceMappingURL=encryption.js.map

package/dist/auth/encryption.js.map

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

package/dist/auth/jwt.d.ts

@@ -0,0 +1,133 @@
+/**
+ * JWT mint + verify for both token shapes.
+ *
+ * Two shapes share one signing key (§6.7) — the discriminator is the `scope`
+ * claim:
+ *
+ * - **Session token** — TTL 24 h, claims `{ iss, sub, username, role, exp }`.
+ *   Required on every protected endpoint.
+ * - **Password-change-only token** — TTL 5 min, claims
+ *   `{ iss, sub, scope: "password_change_only", exp }`. Accepted only by
+ *   `/auth/change-password`; the `scope` claim is the gate.
+ *
+ * Both are HS256 (symmetric HMAC) — appropriate because ai-hub is the only
+ * identity provider; there is no second party that needs to verify without
+ * possessing the secret.
+ *
+ * The signing key lives in `admin_setting.service_token_signing_key` (DB) —
+ * env `SERVICE_TOKEN_SIGNING_KEY` is **bootstrap-only**. Rotation via
+ * `/admin/settings/rotate-signing-key` is sufficient and does not require a
+ * server restart (Step 4 wires that endpoint; Step 2 just defines the
+ * function boundary).
+ *
+ * @see SPECIFICATIONS.md §6.7 — auth model
+ * @see SPECIFICATIONS.md §8.6 — endpoint enforcement
+ */
+import { type JWTPayload } from "jose";
+import type { AIHubRole } from "@data-club/ai-hub";
+/** Issuer string baked into every token's `iss` claim. */
+export declare const JWT_ISSUER = "ai-hub";
+/** Session token lifetime (§6.7). */
+export declare const SESSION_TOKEN_TTL_SECONDS: number;
+/** Password-change-only token lifetime (§6.7). */
+export declare const PASSWORD_CHANGE_TOKEN_TTL_SECONDS: number;
+/** Scope claim that gates the password-change-only token (§6.7). */
+export declare const PASSWORD_CHANGE_SCOPE = "password_change_only";
+/**
+ * Decoded session-token claims. The `role` claim is what the role-enforcement
+ * middleware (Step 3) reads for the §8.2 matrix.
+ */
+export interface SessionTokenClaims extends JWTPayload {
+    /** Issuer — always "ai-hub". */
+    iss: string;
+    /** Subject — the user's id. */
+    sub: string;
+    /** Username, mirrored into the token for log correlation. */
+    username: string;
+    /** Role at mint-time. */
+    role: AIHubRole;
+}
+/** Decoded password-change-only token claims. Carries no `role` (§6.3.4). */
+export interface PasswordChangeTokenClaims extends JWTPayload {
+    /** Issuer — always "ai-hub". */
+    iss: string;
+    /** Subject — the user's id. */
+    sub: string;
+    /** Always `"password_change_only"`. */
+    scope: typeof PASSWORD_CHANGE_SCOPE;
+}
+/**
+ * Discriminated outcome returned by `verifyServiceToken`.
+ *
+ * The role-enforcement middleware (Step 3) calls this exactly once per
+ * request and branches on `kind`:
+ *
+ * - `"session"` → run the §8.2 matrix check against `claims.role`.
+ * - `"password_change"` → reject everywhere except `/auth/change-password`.
+ * - `"invalid"` → 401.
+ *
+ * Keeping the verification at a single function boundary is a §6.7
+ * forward-compat seam — when external IdPs land, a parallel
+ * `verifyExternalToken` slots in alongside without touching every handler.
+ */
+export type VerifyTokenResult = {
+    kind: "session";
+    claims: SessionTokenClaims;
+} | {
+    kind: "password_change";
+    claims: PasswordChangeTokenClaims;
+} | {
+    kind: "invalid";
+};
+/**
+ * Mints a 24-hour session JWT for `user`. `role` is read from the user row
+ * at mint time, not at verify time — rotating someone's role does not change
+ * their existing token (the role embedded in the JWT is what the matrix
+ * sees). Tokens expire in 24 h regardless.
+ *
+ * @param key - signing key from `admin_setting.service_token_signing_key`.
+ * @param user - identity bits to embed in the claims.
+ * @param user.id - user UUID; goes into the `sub` claim.
+ * @param user.username - login identifier; goes into the `username` claim.
+ * @param user.role - access-control role; goes into the `role` claim.
+ * @returns the signed compact JWT string.
+ */
+export declare function mintSessionToken(key: Buffer, user: {
+    id: string;
+    username: string;
+    role: AIHubRole;
+}): Promise<string>;
+/**
+ * Mints a 5-minute password-change-only JWT for `user`. Used on login when
+ * `is_initial_password = true` (§8.5).
+ *
+ * No `role` claim — by design (§6.3.4): the change-only token doesn't grant
+ * any access beyond `/auth/change-password`, and adding role would tempt
+ * future code to use it for other things.
+ *
+ * @param key - signing key.
+ * @param user - identity bits to embed.
+ * @param user.id - user UUID; goes into the `sub` claim.
+ * @returns the signed compact JWT string.
+ */
+export declare function mintPasswordChangeToken(key: Buffer, user: {
+    id: string;
+}): Promise<string>;
+/**
+ * Verifies a token's signature + issuer + expiry, then narrows it to the
+ * session or password-change-only shape based on the `scope` claim.
+ *
+ * Returns `{ kind: "invalid" }` for any failure (bad signature, wrong
+ * issuer, expired, missing required claim, unknown scope) — callers must
+ * treat that as a 401 with a generic message; we do not surface "why".
+ *
+ * **This is the single function boundary** the §6.7 / §8.6 enforcement order
+ * demands — every protected handler in Step 3 calls through here, and a
+ * future `verifyExternalToken` will sit beside it.
+ *
+ * @param key - signing key from `admin_setting.service_token_signing_key`.
+ * @param token - compact JWT string from the `Authorization: Bearer …` header.
+ * @returns a discriminated result the middleware branches on.
+ */
+export declare function verifyServiceToken(key: Buffer, token: string): Promise<VerifyTokenResult>;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/auth/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AAE3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,0DAA0D;AAC1D,eAAO,MAAM,UAAU,WAAW,CAAC;AAKnC,qCAAqC;AACrC,eAAO,MAAM,yBAAyB,QAAe,CAAC;AAEtD,kDAAkD;AAClD,eAAO,MAAM,iCAAiC,QAAS,CAAC;AAExD,oEAAoE;AACpE,eAAO,MAAM,qBAAqB,yBAAyB,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,yBAA0B,SAAQ,UAAU;IAC3D,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,KAAK,EAAE,OAAO,qBAAqB,CAAC;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GACtD,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GACnB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,iBAAiB,CAAC,CAkC5B"}

package/dist/auth/jwt.js

@@ -0,0 +1,147 @@
+/**
+ * JWT mint + verify for both token shapes.
+ *
+ * Two shapes share one signing key (§6.7) — the discriminator is the `scope`
+ * claim:
+ *
+ * - **Session token** — TTL 24 h, claims `{ iss, sub, username, role, exp }`.
+ *   Required on every protected endpoint.
+ * - **Password-change-only token** — TTL 5 min, claims
+ *   `{ iss, sub, scope: "password_change_only", exp }`. Accepted only by
+ *   `/auth/change-password`; the `scope` claim is the gate.
+ *
+ * Both are HS256 (symmetric HMAC) — appropriate because ai-hub is the only
+ * identity provider; there is no second party that needs to verify without
+ * possessing the secret.
+ *
+ * The signing key lives in `admin_setting.service_token_signing_key` (DB) —
+ * env `SERVICE_TOKEN_SIGNING_KEY` is **bootstrap-only**. Rotation via
+ * `/admin/settings/rotate-signing-key` is sufficient and does not require a
+ * server restart (Step 4 wires that endpoint; Step 2 just defines the
+ * function boundary).
+ *
+ * @see SPECIFICATIONS.md §6.7 — auth model
+ * @see SPECIFICATIONS.md §8.6 — endpoint enforcement
+ */
+import { jwtVerify, SignJWT } from "jose";
+/** Issuer string baked into every token's `iss` claim. */
+export const JWT_ISSUER = "ai-hub";
+/** HS256 — symmetric HMAC. Matches the §6.7 "single signing key" stance. */
+const JWT_ALG = "HS256";
+/** Session token lifetime (§6.7). */
+export const SESSION_TOKEN_TTL_SECONDS = 24 * 60 * 60;
+/** Password-change-only token lifetime (§6.7). */
+export const PASSWORD_CHANGE_TOKEN_TTL_SECONDS = 5 * 60;
+/** Scope claim that gates the password-change-only token (§6.7). */
+export const PASSWORD_CHANGE_SCOPE = "password_change_only";
+/**
+ * Mints a 24-hour session JWT for `user`. `role` is read from the user row
+ * at mint time, not at verify time — rotating someone's role does not change
+ * their existing token (the role embedded in the JWT is what the matrix
+ * sees). Tokens expire in 24 h regardless.
+ *
+ * @param key - signing key from `admin_setting.service_token_signing_key`.
+ * @param user - identity bits to embed in the claims.
+ * @param user.id - user UUID; goes into the `sub` claim.
+ * @param user.username - login identifier; goes into the `username` claim.
+ * @param user.role - access-control role; goes into the `role` claim.
+ * @returns the signed compact JWT string.
+ */
+export async function mintSessionToken(key, user) {
+    return new SignJWT({
+        username: user.username,
+        role: user.role,
+    })
+        .setProtectedHeader({ alg: JWT_ALG })
+        .setIssuer(JWT_ISSUER)
+        .setSubject(user.id)
+        .setIssuedAt()
+        .setExpirationTime(`${SESSION_TOKEN_TTL_SECONDS}s`)
+        .sign(key);
+}
+/**
+ * Mints a 5-minute password-change-only JWT for `user`. Used on login when
+ * `is_initial_password = true` (§8.5).
+ *
+ * No `role` claim — by design (§6.3.4): the change-only token doesn't grant
+ * any access beyond `/auth/change-password`, and adding role would tempt
+ * future code to use it for other things.
+ *
+ * @param key - signing key.
+ * @param user - identity bits to embed.
+ * @param user.id - user UUID; goes into the `sub` claim.
+ * @returns the signed compact JWT string.
+ */
+export async function mintPasswordChangeToken(key, user) {
+    return new SignJWT({
+        scope: PASSWORD_CHANGE_SCOPE,
+    })
+        .setProtectedHeader({ alg: JWT_ALG })
+        .setIssuer(JWT_ISSUER)
+        .setSubject(user.id)
+        .setIssuedAt()
+        .setExpirationTime(`${PASSWORD_CHANGE_TOKEN_TTL_SECONDS}s`)
+        .sign(key);
+}
+/**
+ * Verifies a token's signature + issuer + expiry, then narrows it to the
+ * session or password-change-only shape based on the `scope` claim.
+ *
+ * Returns `{ kind: "invalid" }` for any failure (bad signature, wrong
+ * issuer, expired, missing required claim, unknown scope) — callers must
+ * treat that as a 401 with a generic message; we do not surface "why".
+ *
+ * **This is the single function boundary** the §6.7 / §8.6 enforcement order
+ * demands — every protected handler in Step 3 calls through here, and a
+ * future `verifyExternalToken` will sit beside it.
+ *
+ * @param key - signing key from `admin_setting.service_token_signing_key`.
+ * @param token - compact JWT string from the `Authorization: Bearer …` header.
+ * @returns a discriminated result the middleware branches on.
+ */
+export async function verifyServiceToken(key, token) {
+    let payload;
+    try {
+        const verified = await jwtVerify(token, key, {
+            issuer: JWT_ISSUER,
+            algorithms: [JWT_ALG],
+        });
+        payload = verified.payload;
+    }
+    catch {
+        return { kind: "invalid" };
+    }
+    if (typeof payload.sub !== "string" || payload.sub.length === 0) {
+        return { kind: "invalid" };
+    }
+    const scope = payload.scope;
+    if (scope === PASSWORD_CHANGE_SCOPE) {
+        return {
+            kind: "password_change",
+            claims: payload,
+        };
+    }
+    const role = payload.role;
+    const username = payload.username;
+    if (typeof role !== "string" ||
+        !isAIHubRole(role) ||
+        typeof username !== "string") {
+        return { kind: "invalid" };
+    }
+    return { kind: "session", claims: payload };
+}
+/**
+ * Type-guard for the `AIHubRole` enum — keeps `verifyServiceToken` honest
+ * against tokens whose `role` claim was tampered with into something not in
+ * the spec's set.
+ *
+ * @param value - candidate role string.
+ * @returns `true` if `value` is one of the four spec roles.
+ */
+function isAIHubRole(value) {
+    return (value === "user" ||
+        value === "power_user" ||
+        value === "admin" ||
+        value === "super_admin");
+}
+//# sourceMappingURL=jwt.js.map