@rayspec/auth-core 1.5.0

package/dist/session.d.ts

@@ -0,0 +1,18 @@
+/** A freshly minted opaque session secret + the hash to persist. */
+export interface MintedSessionSecret {
+    /** The opaque secret placed in the refresh cookie. Shown to the client ONCE per rotation. */
+    secret: string;
+    /** The HMAC hash to store in sessions.token_hash. */
+    tokenHash: string;
+}
+/** HMAC-SHA256 the opaque session secret with the boot-required pepper (hex digest). */
+export declare function hashSessionSecret(secret: string, pepper?: string): string;
+/** Mint a new opaque session secret (256-bit base64url) + its stored hash. */
+export declare function mintSessionSecret(pepper?: string): MintedSessionSecret;
+/** Constant-time compare a presented secret's hash against a stored hash. */
+export declare function sessionSecretMatches(storedHash: string, presentedSecret: string, pepper?: string): boolean;
+/** A fresh server-minted family id (refresh family). */
+export declare function newFamilyId(): string;
+/** A fresh server-minted JWT id (jti) for an access token. */
+export declare function newJti(): string;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAeA,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAA0B,GAAG,MAAM,CAE5F;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,MAA0B,GAAG,mBAAmB,CAGzF;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,MAAM,GAAE,MAA0B,GACjC,OAAO,CAMT;AAED,wDAAwD;AACxD,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,8DAA8D;AAC9D,wBAAgB,MAAM,IAAI,MAAM,CAE/B"}

package/dist/session.js

@@ -0,0 +1,41 @@
+/**
+ * Opaque server-session secret primitives (DB-free).
+ *
+ * The session cookie carries an OPAQUE secret minted server-side; only its HASH is stored
+ * (sessions.token_hash). The session id is server-minted too (no client-proposed id → no
+ * fixation). `family_id` binds a refresh family for reuse-detection + targeted revoke.
+ *
+ * Hashing: the opaque secret is a ≥256-bit CSPRNG value (high entropy), so a fast keyed HMAC
+ * (SHA-256, keyed by the api-key pepper) is the right primitive — NOT argon2id (reserved for
+ * low-entropy passwords). Verification is by exact hash equality on the indexed unique column
+ * (constant-time compare where a secret is presented).
+ */
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { getApiKeyPepper } from './api-key.js';
+/** HMAC-SHA256 the opaque session secret with the boot-required pepper (hex digest). */
+export function hashSessionSecret(secret, pepper = getApiKeyPepper()) {
+    return createHmac('sha256', pepper).update(secret).digest('hex');
+}
+/** Mint a new opaque session secret (256-bit base64url) + its stored hash. */
+export function mintSessionSecret(pepper = getApiKeyPepper()) {
+    const secret = randomBytes(32).toString('base64url'); // 256-bit
+    return { secret, tokenHash: hashSessionSecret(secret, pepper) };
+}
+/** Constant-time compare a presented secret's hash against a stored hash. */
+export function sessionSecretMatches(storedHash, presentedSecret, pepper = getApiKeyPepper()) {
+    const computed = hashSessionSecret(presentedSecret, pepper);
+    const a = Buffer.from(computed, 'utf8');
+    const b = Buffer.from(storedHash, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/** A fresh server-minted family id (refresh family). */
+export function newFamilyId() {
+    return randomUUID();
+}
+/** A fresh server-minted JWT id (jti) for an access token. */
+export function newJti() {
+    return randomUUID();
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAU/C,wFAAwF;AACxF,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,SAAiB,eAAe,EAAE;IAClF,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,SAAiB,eAAe,EAAE;IAClE,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU;IAChE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,oBAAoB,CAClC,UAAkB,EAClB,eAAuB,EACvB,SAAiB,eAAe,EAAE;IAElC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAC5D,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,WAAW;IACzB,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,MAAM;IACpB,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC"}

package/dist/tokens.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Access-token module — short-lived RFC-9068 JWTs (jose), DB-free + unit-testable.
+ *
+ * Opaque server sessions + SHORT JWT access tokens. The JWT is the stateless, aud+scope-
+ * bound credential a resource server can verify WITHOUT a DB hit; the opaque session (sessions
+ * table) is the single revocation point. Tokens are NEVER persisted.
+ *
+ * Verified doc-first (2026-06-22) against jose 6.2.3 (everything re-exported from the main entry):
+ *   - new SignJWT(claims).setProtectedHeader({alg, kid, typ}).setIssuer/Audience/IssuedAt/
+ *     ExpirationTime/Jti(...).sign(privateKey)
+ *   - jwtVerify(token, keyOrJWKS, { issuer, audience, clockTolerance, typ })
+ *   - importPKCS8(pem, alg) / generateKeyPair(alg) / exportJWK(publicKey) / createLocalJWKSet
+ *
+ * CLAIMS: iss, sub (userId), aud, scope (space-delimited), org_id, mship_role,
+ * jti, iat, exp. exp ~8 min; verify clockTolerance 30s. `typ` is `at+jwt` (RFC 9068).
+ *
+ * KEY ROTATION (documented): each signer has a `kid` (the public-key JWK thumbprint). To rotate,
+ * publish a NEW kid in the JWKS, sign new tokens under it, and KEEP the old public key in the
+ * JWKS for verification until every token minted under it has expired (≥ TTL + clockTolerance).
+ * Then retire the old key. A token's `kid` header selects its verification key, so old + new
+ * coexist during the overlap window and rotation is never an auth outage.
+ */
+import { importPKCS8 } from 'jose';
+/** Issuer — the RaySpec auth control plane. */
+export declare const TOKEN_ISSUER = "rayspec-auth";
+/** The control-plane API audience (this server). The agent runtime uses a DIFFERENT aud. */
+export declare const AUDIENCE_API = "rayspec-api";
+/** The agent-runtime resource-server audience (forward-compatible; not minted by default). */
+export declare const AUDIENCE_AGENT_RUNTIME = "rayspec-agent-runtime";
+/** Access-token TTL (~8 min) and verify clock tolerance (~30s). */
+export declare const ACCESS_TOKEN_TTL_SECONDS: number;
+export declare const CLOCK_TOLERANCE_SECONDS = 30;
+/** RFC 9068 access-token media type — set in the JWT `typ` header and checked on verify. */
+export declare const ACCESS_TOKEN_TYP = "at+jwt";
+/** Supported signing algorithms (RS256 primary, EdDSA accepted). */
+export type SigningAlg = 'RS256' | 'EdDSA';
+/**
+ * The private-key type jose hands back from importPKCS8 / generateKeyPair. Derived from the API
+ * rather than naming the WebCrypto `CryptoKey` global (our tsconfig lib is ES2023, no DOM types),
+ * so the signer is typed without pulling in the DOM lib.
+ */
+type JosePrivateKey = Awaited<ReturnType<typeof importPKCS8>>;
+/** The claims a RaySpec access token carries (beyond the registered iss/aud/sub/iat/exp/jti). */
+export interface AccessTokenClaims {
+    /** Subject — the global user id. */
+    userId: string;
+    /** The active org (tenant) this token is scoped to (may be undefined before an org is chosen). */
+    orgId?: string;
+    /** The caller's membership role in `orgId` at mint time (read-staleness bounded; never trusted
+     * for sensitive writes — those re-check live, see authz.ts). */
+    mshipRole?: string;
+    /** OAuth-style scopes granted to this token. */
+    scopes?: string[];
+    /** Audience (defaults to the control-plane API). */
+    audience?: string;
+}
+/** A verified token's normalized claims (what callers read after verifyAccessToken). */
+export interface VerifiedAccessToken {
+    userId: string;
+    orgId?: string;
+    mshipRole?: string;
+    scopes: string[];
+    jti?: string;
+    audience: string;
+}
+/**
+ * A token signer bound to ONE key (one kid). Construct via `createSigner` (from a PEM) or
+ * `createSignerFromKeyPair` (tests). Holds the private key for signing + the public JWK for the
+ * JWKS endpoint. The verifier resolves a token's `kid` against a key set (see JwksProvider).
+ */
+export declare class TokenSigner {
+    readonly kid: string;
+    readonly alg: SigningAlg;
+    private readonly privateKey;
+    private readonly publicJwk;
+    /** The access-token TTL (seconds) this signer mints with. Default ACCESS_TOKEN_TTL_SECONDS (480). */
+    private readonly ttlSeconds;
+    constructor(kid: string, alg: SigningAlg, privateKey: JosePrivateKey, publicJwk: Record<string, unknown>, ttlSeconds?: number);
+    /** Build a signer from a private + public CryptoKey pair (used by tests + createSigner). */
+    static fromKeys(privateKey: JosePrivateKey, publicKey: JosePrivateKey, alg: SigningAlg, ttlSeconds?: number): Promise<TokenSigner>;
+    /** The public JWK (with kid/use/alg) to publish in the JWKS endpoint. */
+    publicKeyJwk(): Record<string, unknown>;
+    /**
+     * The configured access-token TTL in seconds (default ACCESS_TOKEN_TTL_SECONDS). Callers (the auth
+     * routes) report THIS in the response `expiresIn` so it can never drift from the minted token's `exp`.
+     */
+    get accessTokenTtlSeconds(): number;
+    /** Mint a signed access token. exp = now + the signer's configured ttlSeconds (default ACCESS_TOKEN_TTL_SECONDS). */
+    mint(claims: AccessTokenClaims, jti: string): Promise<string>;
+}
+/**
+ * Build a signer from a PKCS#8 PEM private key + its algorithm. The PUBLIC key for the JWKS is
+ * derived from the private key via jose's import (RS256/EdDSA carry the public component).
+ * RS256 PKCS#8 is the documented default (RAYSPEC_JWT_SIGNING_KEY).
+ */
+export declare function createSigner(pkcs8Pem: string, alg?: SigningAlg, ttlSeconds?: number): Promise<TokenSigner>;
+/**
+ * The JWKS view + the verifier. Holds one or more public JWKs (the active signer plus any
+ * not-yet-retired rotated keys) and verifies a token's signature against the matching kid, its
+ * issuer, audience, exp (with clock tolerance), and the `at+jwt` type.
+ */
+export declare class JwksProvider {
+    private readonly jwks;
+    constructor(publicJwks: Record<string, unknown>[]);
+    /** The public JWKS document served at GET /v1/oauth/jwks. */
+    toJwks(): {
+        keys: Record<string, unknown>[];
+    };
+    /**
+     * Verify an access token. Checks signature (by kid → key), issuer, audience, exp (±30s), and
+     * the RFC-9068 `typ`. Throws on any failure (caller maps to 401). `expectedAudience` defaults
+     * to the control-plane API audience — a token minted for a different aud is rejected here.
+     */
+    verify(token: string, expectedAudience?: string): Promise<VerifiedAccessToken>;
+}
+export {};
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

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

package/dist/tokens.js

@@ -0,0 +1,150 @@
+/**
+ * Access-token module — short-lived RFC-9068 JWTs (jose), DB-free + unit-testable.
+ *
+ * Opaque server sessions + SHORT JWT access tokens. The JWT is the stateless, aud+scope-
+ * bound credential a resource server can verify WITHOUT a DB hit; the opaque session (sessions
+ * table) is the single revocation point. Tokens are NEVER persisted.
+ *
+ * Verified doc-first (2026-06-22) against jose 6.2.3 (everything re-exported from the main entry):
+ *   - new SignJWT(claims).setProtectedHeader({alg, kid, typ}).setIssuer/Audience/IssuedAt/
+ *     ExpirationTime/Jti(...).sign(privateKey)
+ *   - jwtVerify(token, keyOrJWKS, { issuer, audience, clockTolerance, typ })
+ *   - importPKCS8(pem, alg) / generateKeyPair(alg) / exportJWK(publicKey) / createLocalJWKSet
+ *
+ * CLAIMS: iss, sub (userId), aud, scope (space-delimited), org_id, mship_role,
+ * jti, iat, exp. exp ~8 min; verify clockTolerance 30s. `typ` is `at+jwt` (RFC 9068).
+ *
+ * KEY ROTATION (documented): each signer has a `kid` (the public-key JWK thumbprint). To rotate,
+ * publish a NEW kid in the JWKS, sign new tokens under it, and KEEP the old public key in the
+ * JWKS for verification until every token minted under it has expired (≥ TTL + clockTolerance).
+ * Then retire the old key. A token's `kid` header selects its verification key, so old + new
+ * coexist during the overlap window and rotation is never an auth outage.
+ */
+import { calculateJwkThumbprint, createLocalJWKSet, exportJWK, importPKCS8, jwtVerify, SignJWT, } from 'jose';
+/** Issuer — the RaySpec auth control plane. */
+export const TOKEN_ISSUER = 'rayspec-auth';
+/** The control-plane API audience (this server). The agent runtime uses a DIFFERENT aud. */
+export const AUDIENCE_API = 'rayspec-api';
+/** The agent-runtime resource-server audience (forward-compatible; not minted by default). */
+export const AUDIENCE_AGENT_RUNTIME = 'rayspec-agent-runtime';
+/** Access-token TTL (~8 min) and verify clock tolerance (~30s). */
+export const ACCESS_TOKEN_TTL_SECONDS = 8 * 60;
+export const CLOCK_TOLERANCE_SECONDS = 30;
+/** RFC 9068 access-token media type — set in the JWT `typ` header and checked on verify. */
+export const ACCESS_TOKEN_TYP = 'at+jwt';
+/**
+ * A token signer bound to ONE key (one kid). Construct via `createSigner` (from a PEM) or
+ * `createSignerFromKeyPair` (tests). Holds the private key for signing + the public JWK for the
+ * JWKS endpoint. The verifier resolves a token's `kid` against a key set (see JwksProvider).
+ */
+export class TokenSigner {
+    kid;
+    alg;
+    privateKey;
+    publicJwk;
+    /** The access-token TTL (seconds) this signer mints with. Default ACCESS_TOKEN_TTL_SECONDS (480). */
+    ttlSeconds;
+    constructor(kid, alg, privateKey, publicJwk, ttlSeconds = ACCESS_TOKEN_TTL_SECONDS) {
+        this.kid = kid;
+        this.alg = alg;
+        this.privateKey = privateKey;
+        this.publicJwk = publicJwk;
+        this.ttlSeconds = ttlSeconds;
+    }
+    /** Build a signer from a private + public CryptoKey pair (used by tests + createSigner). */
+    static async fromKeys(privateKey, publicKey, alg, ttlSeconds = ACCESS_TOKEN_TTL_SECONDS) {
+        const publicJwk = (await exportJWK(publicKey));
+        const kid = await calculateJwkThumbprint(publicJwk);
+        publicJwk.kid = kid;
+        publicJwk.use = 'sig';
+        publicJwk.alg = alg;
+        return new TokenSigner(kid, alg, privateKey, publicJwk, ttlSeconds);
+    }
+    /** The public JWK (with kid/use/alg) to publish in the JWKS endpoint. */
+    publicKeyJwk() {
+        return { ...this.publicJwk };
+    }
+    /**
+     * The configured access-token TTL in seconds (default ACCESS_TOKEN_TTL_SECONDS). Callers (the auth
+     * routes) report THIS in the response `expiresIn` so it can never drift from the minted token's `exp`.
+     */
+    get accessTokenTtlSeconds() {
+        return this.ttlSeconds;
+    }
+    /** Mint a signed access token. exp = now + the signer's configured ttlSeconds (default ACCESS_TOKEN_TTL_SECONDS). */
+    async mint(claims, jti) {
+        const payload = {};
+        if (claims.orgId !== undefined)
+            payload.org_id = claims.orgId;
+        if (claims.mshipRole !== undefined)
+            payload.mship_role = claims.mshipRole;
+        payload.scope = (claims.scopes ?? []).join(' ');
+        return new SignJWT(payload)
+            .setProtectedHeader({ alg: this.alg, kid: this.kid, typ: ACCESS_TOKEN_TYP })
+            .setIssuer(TOKEN_ISSUER)
+            .setSubject(claims.userId)
+            .setAudience(claims.audience ?? AUDIENCE_API)
+            .setIssuedAt()
+            .setExpirationTime(`${this.ttlSeconds}s`)
+            .setJti(jti)
+            .sign(this.privateKey);
+    }
+}
+/**
+ * Build a signer from a PKCS#8 PEM private key + its algorithm. The PUBLIC key for the JWKS is
+ * derived from the private key via jose's import (RS256/EdDSA carry the public component).
+ * RS256 PKCS#8 is the documented default (RAYSPEC_JWT_SIGNING_KEY).
+ */
+export async function createSigner(pkcs8Pem, alg = 'RS256', ttlSeconds = ACCESS_TOKEN_TTL_SECONDS) {
+    const privateKey = await importPKCS8(pkcs8Pem, alg, { extractable: true });
+    // Derive the public JWK from the private key: export the private JWK, strip the private fields.
+    const privJwk = (await exportJWK(privateKey));
+    const pubJwk = { ...privJwk };
+    // Remove private-key components so the JWKS never exposes private material.
+    for (const k of ['d', 'p', 'q', 'dp', 'dq', 'qi'])
+        delete pubJwk[k];
+    const kid = await calculateJwkThumbprint(pubJwk);
+    pubJwk.kid = kid;
+    pubJwk.use = 'sig';
+    pubJwk.alg = alg;
+    return new TokenSigner(kid, alg, privateKey, pubJwk, ttlSeconds);
+}
+/**
+ * The JWKS view + the verifier. Holds one or more public JWKs (the active signer plus any
+ * not-yet-retired rotated keys) and verifies a token's signature against the matching kid, its
+ * issuer, audience, exp (with clock tolerance), and the `at+jwt` type.
+ */
+export class JwksProvider {
+    jwks;
+    constructor(publicJwks) {
+        this.jwks = { keys: publicJwks };
+    }
+    /** The public JWKS document served at GET /v1/oauth/jwks. */
+    toJwks() {
+        return { keys: this.jwks.keys.map((k) => ({ ...k })) };
+    }
+    /**
+     * Verify an access token. Checks signature (by kid → key), issuer, audience, exp (±30s), and
+     * the RFC-9068 `typ`. Throws on any failure (caller maps to 401). `expectedAudience` defaults
+     * to the control-plane API audience — a token minted for a different aud is rejected here.
+     */
+    async verify(token, expectedAudience = AUDIENCE_API) {
+        const jwkSet = createLocalJWKSet(this.jwks);
+        const { payload } = await jwtVerify(token, jwkSet, {
+            issuer: TOKEN_ISSUER,
+            audience: expectedAudience,
+            clockTolerance: CLOCK_TOLERANCE_SECONDS,
+            typ: ACCESS_TOKEN_TYP,
+        });
+        const scopeClaim = typeof payload.scope === 'string' ? payload.scope : '';
+        return {
+            userId: typeof payload.sub === 'string' ? payload.sub : '',
+            orgId: typeof payload.org_id === 'string' ? payload.org_id : undefined,
+            mshipRole: typeof payload.mship_role === 'string' ? payload.mship_role : undefined,
+            scopes: scopeClaim.length > 0 ? scopeClaim.split(' ') : [],
+            jti: typeof payload.jti === 'string' ? payload.jti : undefined,
+            audience: expectedAudience,
+        };
+    }
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@rayspec/auth-core",
+  "version": "1.5.0",
+  "private": false,
+  "files": [
+    "dist"
+  ],
+  "license": "FSL-1.1-ALv2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "argon2": "0.44.0",
+    "jose": "6.2.3",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "22.12.0",
+    "typescript": "5.9.3",
+    "vitest": "4.1.9"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}