@relyt/auth 0.0.0-stage → 0.1.0

package/dist/social.js

@@ -0,0 +1,241 @@
+// Cross-site social sign-in. Web APIs only.
+// Handoff codes, PKCE verifiers and session tokens never reach errors, events or logs.
+import { retryAfterMs } from "./client.js";
+import { RelytAuthError } from "./errors.js";
+import { normalizeIssuer } from "./issuer.js";
+import { num } from "./options.js";
+/** sessionStorage key: one pending sign-in record `{v, mode, base, t}` (single use, removed when read by complete). */
+export const SOCIAL_PKCE_STORAGE_KEY = "relyt.auth.social.pkce";
+const CODE_RE = /^[A-Za-z0-9_-]{43}$/;
+const OAUTH_ERROR_RE = /^[a-z0-9_]{1,64}$/;
+const MODES = new Set(["fragment", "query"]);
+const CODE_PARAM = "relyt_code";
+const ERROR_PARAM = "error";
+/** Parameters the callback page must remove from the address bar (code, error and its description). */
+const STRIP_PARAMS = [CODE_PARAM, ERROR_PARAM, "error_description"];
+const cfg = (option) => new RelytAuthError("config", { option });
+function base64url(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function authBase(s) {
+    try {
+        return normalizeIssuer(s);
+    }
+    catch {
+        throw cfg("authUrl");
+    }
+}
+const optStr = (v, option) => {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string" || v === "")
+        throw cfg(option);
+    return v;
+};
+/** Validates options, generates verifier and S256 challenge, builds the start URL; touches no storage and does not navigate. */
+async function buildStart(o) {
+    if (typeof o !== "object" || o === null)
+        throw cfg("authUrl");
+    const base = authBase(o.authUrl);
+    const provider = optStr(o.provider, "provider");
+    const callbackURL = optStr(o.callbackURL, "callbackURL");
+    if (provider === undefined)
+        throw cfg("provider");
+    if (callbackURL === undefined)
+        throw cfg("callbackURL");
+    const errorCallbackURL = optStr(o.errorCallbackURL, "errorCallbackURL");
+    const newUserCallbackURL = optStr(o.newUserCallbackURL, "newUserCallbackURL");
+    const mode = o.responseMode ?? "fragment";
+    if (!MODES.has(mode))
+        throw cfg("responseMode");
+    const raw = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(raw);
+    const codeVerifier = base64url(raw);
+    const challenge = base64url(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(codeVerifier))));
+    const q = new URLSearchParams();
+    q.set("provider", provider);
+    q.set("callbackURL", callbackURL);
+    if (errorCallbackURL !== undefined)
+        q.set("errorCallbackURL", errorCallbackURL);
+    if (newUserCallbackURL !== undefined)
+        q.set("newUserCallbackURL", newUserCallbackURL);
+    q.set("code_challenge", challenge);
+    q.set("code_challenge_method", "S256");
+    q.set("response_mode", mode);
+    return { url: `${base}/api/auth/relyt/social/start?${q.toString()}`, codeVerifier, base, mode };
+}
+/**
+ * Pure builder (works in browsers and Node): returns the start URL and the verifier; the caller keeps the verifier and navigates.
+ * Used for the server-proxied flow: the server generates it, binds the verifier to its own session, and redeems the code with exchangeHandoffCode after the callback.
+ */
+export async function createSocialStart(o) {
+    const { url, codeVerifier } = await buildStart(o);
+    return { url, codeVerifier };
+}
+/** Browser entry: build → store the pending record → navigate the top-level window to the auth host. */
+export async function startSocialSignIn(o) {
+    const { url, codeVerifier: v, base, mode } = await buildStart(o);
+    try {
+        globalThis.sessionStorage.setItem(SOCIAL_PKCE_STORAGE_KEY, JSON.stringify({ v, mode, base, t: Date.now() }));
+    }
+    catch {
+        throw cfg("sessionStorage");
+    }
+    globalThis.location.assign(url);
+}
+/** Lifetime of a pending record: older records are treated as missing. */
+const PENDING_TTL_MS = 10 * 60 * 1000;
+/** Takes and removes the pending record (single use); unreadable / invalid ⇒ null. */
+function takePending() {
+    let raw = null;
+    try {
+        raw = globalThis.sessionStorage.getItem(SOCIAL_PKCE_STORAGE_KEY);
+        globalThis.sessionStorage.removeItem(SOCIAL_PKCE_STORAGE_KEY);
+    }
+    catch {
+        return null;
+    }
+    if (raw === null)
+        return null;
+    try {
+        const p = JSON.parse(raw);
+        if (p && typeof p.v === "string" && CODE_RE.test(p.v) && typeof p.mode === "string" && MODES.has(p.mode) &&
+            typeof p.base === "string" && typeof p.t === "number" && Number.isFinite(p.t)) {
+            return { v: p.v, mode: p.mode, base: p.base, t: p.t };
+        }
+    }
+    catch {
+        /* a corrupt record is treated as missing */
+    }
+    return null;
+}
+/** (1) read the URL (2) remove code / error from the address bar; runs before anything else, including option validation. */
+function readAndCleanUrl() {
+    const url = new URL(globalThis.location.href);
+    const frag = new URLSearchParams(url.hash.startsWith("#") ? url.hash.slice(1) : url.hash);
+    const fromQuery = url.searchParams.getAll(CODE_PARAM);
+    const fromFrag = frag.getAll(CODE_PARAM);
+    const err = url.searchParams.get(ERROR_PARAM) ?? frag.get(ERROR_PARAM);
+    let changed = false;
+    if (STRIP_PARAMS.some((k) => url.searchParams.has(k))) {
+        for (const k of STRIP_PARAMS)
+            url.searchParams.delete(k);
+        changed = true;
+    }
+    if (STRIP_PARAMS.some((k) => frag.has(k))) {
+        for (const k of STRIP_PARAMS)
+            frag.delete(k);
+        const rest = frag.toString();
+        url.hash = rest === "" ? "" : `#${rest}`;
+        changed = true;
+    }
+    if (changed)
+        globalThis.history.replaceState(globalThis.history.state, "", url.href);
+    return { fromQuery, fromFrag, err };
+}
+/** The complete() call in progress: concurrent calls share one promise, reset when it settles (success or failure). */
+let inFlight = null;
+/**
+ * Call on the registered callback page: clean the address bar → validate options → take the verifier → exchange → deliver the session token.
+ * Re-entrant: a call while one is in progress (e.g. React StrictMode's double effect) returns the same promise, so the code is exchanged
+ * and the token delivered exactly once; options passed to the later call are ignored.
+ */
+export function completeSocialSignIn(o) {
+    if (inFlight !== null)
+        return inFlight;
+    const p = runComplete(o).finally(() => {
+        if (inFlight === p)
+            inFlight = null;
+    });
+    inFlight = p;
+    return p;
+}
+async function runComplete(o) {
+    const { fromQuery, fromFrag, err } = readAndCleanUrl();
+    if (typeof o !== "object" || o === null)
+        throw cfg("authUrl");
+    const base = authBase(o.authUrl);
+    if (typeof o.onSessionToken !== "function")
+        throw cfg("onSessionToken");
+    const timeoutMs = num(o.timeoutMs, 15_000, "timeoutMs", (n) => Number.isInteger(n) && n >= 1_000 && n <= 60_000);
+    // (3) take and remove the record (single use).
+    const pending = takePending();
+    // (4) error callback (checked before the missing-record check).
+    if (err !== null) {
+        throw new RelytAuthError("oauth_error", { retryable: false, oauthError: OAUTH_ERROR_RE.test(err) ? err : "unknown" });
+    }
+    // (5) no record started in this browser session ⇒ never exchange (defends against planted codes, i.e. login CSRF).
+    if (pending === null)
+        throw new RelytAuthError("no_pending_sign_in", { retryable: false });
+    // (5') the record must have been started for the same auth host and not be expired; otherwise treat it as missing, no separate error code.
+    if (pending.base !== base || Date.now() - pending.t > PENDING_TTL_MS) {
+        throw new RelytAuthError("no_pending_sign_in", { retryable: false });
+    }
+    // (6) take the code only from the location named by the record's mode; exactly one, well-formed.
+    const codes = pending.mode === "fragment" ? fromFrag : fromQuery;
+    const code = codes.length === 1 ? codes[0] : undefined;
+    if (code === undefined || !CODE_RE.test(code))
+        throw new RelytAuthError("missing_code", { retryable: false });
+    const { sessionToken } = await exchange(base, code, pending.v, o.fetch, timeoutMs);
+    o.client?.clear();
+    o.onSessionToken(sessionToken);
+}
+/** Server-side proxy (Node / Next route handler): no Origin header, exchanges directly. */
+export async function exchangeHandoffCode(o) {
+    if (typeof o !== "object" || o === null)
+        throw cfg("authUrl");
+    const base = authBase(o.authUrl);
+    if (typeof o.code !== "string" || o.code === "")
+        throw cfg("code");
+    if (typeof o.codeVerifier !== "string" || o.codeVerifier === "")
+        throw cfg("codeVerifier");
+    const timeoutMs = num(o.timeoutMs, 15_000, "timeoutMs", (n) => Number.isInteger(n) && n >= 1_000 && n <= 60_000);
+    return exchange(base, o.code, o.codeVerifier, o.fetch, timeoutMs);
+}
+/** Single POST, no retry (codes are single use); status → error code mapping is documented in the README. */
+async function exchange(base, code, codeVerifier, f, timeoutMs) {
+    const doFetch = f ?? ((input, init) => globalThis.fetch(input, init));
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    let res;
+    try {
+        res = await doFetch(`${base}/api/auth/relyt/exchange`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ code, code_verifier: codeVerifier }),
+            credentials: "omit",
+            signal: ac.signal,
+        });
+        await res.text().catch(() => "");
+    }
+    catch {
+        throw new RelytAuthError("network", { retryable: false });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const s = res.status;
+    if (s === 200) {
+        const t = res.headers.get("set-auth-token");
+        if (t === null || t === "")
+            throw new RelytAuthError("bad_response", { status: 200, retryable: false });
+        return { sessionToken: t };
+    }
+    if (s === 400)
+        throw new RelytAuthError("invalid_handoff_code", { status: s, retryable: false });
+    // 403 is only reachable by non-browser callers that send their own Origin: in a browser an unregistered origin fails the CORS preflight first, which surfaces as network.
+    if (s === 403)
+        throw new RelytAuthError("invalid_origin", { status: s, retryable: false });
+    if (s === 429) {
+        // Reuses the client's parser (integer seconds / IMF-fixdate, clamped to [0, 10] s, invalid ⇒ 2 s); header missing ⇒ omitted.
+        const ra = res.headers.get("retry-after");
+        const retryAfterS = ra === null ? undefined : retryAfterMs(ra) / 1000;
+        throw new RelytAuthError("rate_limited", { status: s, retryable: false, ...(retryAfterS === undefined ? {} : { retryAfterS }) });
+    }
+    if (s === 503)
+        throw new RelytAuthError("unavailable", { status: s, retryable: false });
+    throw new RelytAuthError("bad_response", { status: s, retryable: false });
+}

package/dist/verify.d.ts

@@ -0,0 +1,26 @@
+import { type RelytClaims } from "./claims.js";
+import { RelytAuthError, type AuthEvent } from "./errors.js";
+export interface VerifierOptions {
+    /** Expected value of both iss and aud. */
+    issuer: string;
+    /** Default `${issuer}/.well-known/jwks.json`; only changes where keys are fetched from. */
+    jwksUrl?: string;
+    /** Default 30, ≤ 60 (the JWKS keeps a retired key for only 60 s beyond the token TTL). */
+    clockToleranceS?: number;
+    /** Default 900. */
+    maxTokenAgeS?: number;
+    /** Default 30_000. */
+    cooldownMs?: number;
+    /** Default 5_000. */
+    timeoutMs?: number;
+    onEvent?: (e: AuthEvent) => void;
+}
+/** Marker for a remote key set that failed while fetching keys (network / non-200 / non-JSON / timeout / invalid JWKS). */
+export declare class JwksUnavailable extends Error {
+    constructor();
+}
+/** Maps errors by `err.code`; anything unknown becomes invalid_token (fail closed). The jose error is not kept (its payload contains claims). */
+export declare function mapJoseError(err: unknown): RelytAuthError;
+export declare function createVerifier(o: VerifierOptions): (token: string) => Promise<RelytClaims>;
+/** Claim options are resolved on every call; remote key sets are reused per cache key. */
+export declare function verifyToken(token: string, o: VerifierOptions): Promise<RelytClaims>;

package/dist/verify.js

@@ -0,0 +1,128 @@
+/**
+ * Server-side token verification. Web APIs only (jose's webapi build).
+ * Fixed: algorithms ["EdDSA"] (not configurable), issuer = audience = the issuer given at construction (never derived from the token).
+ */
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { checkClaimsShape } from "./claims.js";
+import { RelytAuthError } from "./errors.js";
+import { MAX_CLOCK_TOLERANCE_S, TOKEN_TTL_S } from "./constants.js";
+import { normalizeIssuer, normalizeJwksUrl } from "./issuer.js";
+import { num } from "./options.js";
+const ALGORITHMS = ["EdDSA"];
+const REQUIRED_CLAIMS = ["exp", "iat", "sub"];
+const CACHE_MAX_AGE_MS = 300_000;
+// jose's createRemoteJWKSet requires integer milliseconds; a non-integer throws a synchronous TypeError that would surface as invalid_token (every request 401). The cap prevents setTimeout overflow.
+const MAX_TIMEOUT_MS = 60_000;
+const MAX_COOLDOWN_MS = 3_600_000;
+const JWKS_CACHE_LIMIT = 64;
+function resolve(o) {
+    if (typeof o !== "object" || o === null)
+        throw new RelytAuthError("config", { option: "issuer" });
+    const issuer = normalizeIssuer(o.issuer);
+    const r = {
+        issuer,
+        jwksHref: normalizeJwksUrl(o.jwksUrl ?? `${issuer}/.well-known/jwks.json`),
+        clockToleranceS: num(o.clockToleranceS, 30, "clockToleranceS", (n) => n >= 0 && n <= MAX_CLOCK_TOLERANCE_S),
+        maxTokenAgeS: num(o.maxTokenAgeS, TOKEN_TTL_S, "maxTokenAgeS", (n) => n > 0),
+        cooldownMs: num(o.cooldownMs, 30_000, "cooldownMs", (n) => Number.isInteger(n) && n >= 0 && n <= MAX_COOLDOWN_MS),
+        timeoutMs: num(o.timeoutMs, 5_000, "timeoutMs", (n) => Number.isInteger(n) && n > 0 && n <= MAX_TIMEOUT_MS),
+    };
+    if (o.onEvent !== undefined)
+        r.onEvent = o.onEvent;
+    return r;
+}
+/** Marker for a remote key set that failed while fetching keys (network / non-200 / non-JSON / timeout / invalid JWKS). */
+export class JwksUnavailable extends Error {
+    constructor() {
+        super("jwks unavailable");
+    }
+}
+const KID_MISS = new Set(["ERR_JWKS_NO_MATCHING_KEY", "ERR_JWKS_MULTIPLE_MATCHING_KEYS"]);
+const JWKS_DOWN = new Set(["ERR_JWKS_TIMEOUT", "ERR_JWKS_INVALID"]);
+/** Maps errors by `err.code`; anything unknown becomes invalid_token (fail closed). The jose error is not kept (its payload contains claims). */
+export function mapJoseError(err) {
+    if (err instanceof RelytAuthError)
+        return err;
+    if (err instanceof JwksUnavailable)
+        return new RelytAuthError("jwks_unavailable");
+    const code = typeof err === "object" && err !== null ? err.code : undefined;
+    if (typeof code === "string" && JWKS_DOWN.has(code))
+        return new RelytAuthError("jwks_unavailable");
+    return new RelytAuthError("invalid_token");
+}
+/** Process-wide remote JWKS cache: caches the key sets only, keyed by jwksUrl + cooldown + timeout + cacheMaxAge; LRU of 64. */
+const jwksCache = new Map();
+function remoteKeys(r) {
+    const key = JSON.stringify([r.jwksHref, r.cooldownMs, r.timeoutMs, CACHE_MAX_AGE_MS]);
+    const hit = jwksCache.get(key);
+    if (hit) {
+        jwksCache.delete(key);
+        jwksCache.set(key, hit);
+        return hit;
+    }
+    const remote = createRemoteJWKSet(new URL(r.jwksHref), {
+        cooldownDuration: r.cooldownMs,
+        cacheMaxAge: CACHE_MAX_AGE_MS,
+        timeoutDuration: r.timeoutMs,
+    });
+    // kid miss ⇒ rethrow as-is (invalid_token); any failure to obtain the key set ⇒ JwksUnavailable (the middleware answers 503, not 401)
+    const getKey = async (header, token) => {
+        try {
+            return await remote(header, token);
+        }
+        catch (e) {
+            const code = typeof e === "object" && e !== null ? e.code : undefined;
+            if (typeof code === "string" && KID_MISS.has(code))
+                throw e;
+            if (code === "ERR_JOSE_NOT_SUPPORTED" || code === "ERR_JWK_INVALID")
+                throw e;
+            throw new JwksUnavailable();
+        }
+    };
+    jwksCache.set(key, getKey);
+    if (jwksCache.size > JWKS_CACHE_LIMIT)
+        jwksCache.delete(jwksCache.keys().next().value);
+    return getKey;
+}
+async function verifyWith(r, token) {
+    try {
+        if (typeof token !== "string" || token === "")
+            throw new RelytAuthError("invalid_token");
+        const { payload } = await jwtVerify(token, remoteKeys(r), {
+            algorithms: ALGORITHMS,
+            issuer: r.issuer,
+            audience: r.issuer,
+            requiredClaims: REQUIRED_CLAIMS,
+            clockTolerance: r.clockToleranceS,
+            maxTokenAge: r.maxTokenAgeS,
+        });
+        // Post-check: jose's maxTokenAge only bounds the age of iat, not the issued lifetime
+        const life = payload.exp - payload.iat;
+        if (!(life > 0 && life <= r.maxTokenAgeS))
+            throw new RelytAuthError("invalid_token");
+        if (!checkClaimsShape(payload))
+            throw new RelytAuthError("invalid_claims");
+        return structuredClone(payload);
+    }
+    catch (e) {
+        const err = mapJoseError(e);
+        emit(r, { type: "verify_failed", code: err.code, issuer: r.issuer });
+        throw err;
+    }
+}
+function emit(r, e) {
+    try {
+        r.onEvent?.(e);
+    }
+    catch {
+        // an observer callback must not affect the verification result
+    }
+}
+export function createVerifier(o) {
+    const r = resolve(o);
+    return (token) => verifyWith(r, token);
+}
+/** Claim options are resolved on every call; remote key sets are reused per cache key. */
+export async function verifyToken(token, o) {
+    return verifyWith(resolve(o), token);
+}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@relyt/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Relyt managed-auth SDK: client token cache and server-side JWT verification (EdDSA, remote JWKS), plus a Next.js middleware entry.",
+  "keywords": [
+    "relyt",
+    "auth",
+    "jwt",
+    "jwks",
+    "eddsa",
+    "nextjs",
+    "middleware"
+  ],
+  "license": "MIT",
+  "author": "Relyt",
+  "homepage": "https://github.com/relytcloud/relyt-auth-js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/relytcloud/relyt-auth-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/relytcloud/relyt-auth-js/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.18.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsc -p tsconfig.build.json && vitest run",
+    "typecheck": "tsc --noEmit -p .",
+    "prepublishOnly": "pnpm run build && pnpm run test"
+  },
+  "dependencies": {
+    "jose": "6.2.13"
+  },
+  "peerDependencies": {
+    "next": "^14.2.35 || >=15.5.28 <16"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "next": "15.5.28",
+    "react": "19.2.9",
+    "react-dom": "19.2.9",
+    "typescript": "5.9.3",
+    "vitest": "5.0.5"
+  }
+}