@relyt/auth 0.0.0-stage → 0.1.0

package/dist/errors.js

@@ -0,0 +1,42 @@
+const MESSAGES = {
+    unauthenticated: "not authenticated",
+    unavailable: "auth service unavailable",
+    network: "network error",
+    bad_response: "unexpected response from auth service",
+    invalid_token: "invalid token",
+    invalid_claims: "invalid token claims",
+    jwks_unavailable: "signing keys unavailable",
+    config: "invalid configuration",
+    invalid_handoff_code: "invalid or expired sign-in code",
+    invalid_origin: "origin not trusted by auth service",
+    rate_limited: "too many requests",
+    no_pending_sign_in: "no pending sign-in in this browser session",
+    missing_code: "sign-in code missing from callback URL",
+    oauth_error: "social sign-in failed",
+};
+const RETRYABLE = new Set(["unavailable", "network", "jwks_unavailable"]);
+export class RelytAuthError extends Error {
+    code;
+    retryable;
+    status;
+    /** `config` only: name of the offending option (option names are not secret). */
+    option;
+    /** `rate_limited` only: integer seconds from the `retry-after` response header (when present and valid). */
+    retryAfterS;
+    /** `oauth_error` only: the `error` value from the callback URL, filtered by `^[a-z0-9_]{1,64}$`, otherwise `"unknown"`. */
+    oauthError;
+    constructor(code, o = {}) {
+        super(MESSAGES[code]);
+        this.name = "RelytAuthError";
+        this.code = code;
+        this.retryable = o.retryable ?? RETRYABLE.has(code);
+        if (o.status !== undefined)
+            this.status = o.status;
+        if (o.option !== undefined)
+            this.option = o.option;
+        if (o.retryAfterS !== undefined)
+            this.retryAfterS = o.retryAfterS;
+        if (o.oauthError !== undefined)
+            this.oauthError = o.oauthError;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { RelytAuthError, type RelytAuthErrorCode, type AuthEvent } from "./errors.js";
+export { CLAIM_KEYS, REGISTERED_CLAIM_KEYS, type RelytClaims } from "./claims.js";
+export { createVerifier, verifyToken, type VerifierOptions } from "./verify.js";
+export { createAuthClient, type AuthClient, type AuthClientOptions } from "./client.js";
+export { startSocialSignIn, createSocialStart, completeSocialSignIn, exchangeHandoffCode, SOCIAL_PKCE_STORAGE_KEY, type StartSocialSignInOptions, type SocialStart, type CompleteSocialSignInOptions, type ExchangeHandoffCodeOptions, type SocialResponseMode, } from "./social.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// @relyt/auth main entry (Web APIs only: works in browsers, Node and the Next.js edge runtime).
+export { RelytAuthError } from "./errors.js";
+export { CLAIM_KEYS, REGISTERED_CLAIM_KEYS } from "./claims.js";
+export { createVerifier, verifyToken } from "./verify.js";
+export { createAuthClient } from "./client.js";
+export { startSocialSignIn, createSocialStart, completeSocialSignIn, exchangeHandoffCode, SOCIAL_PKCE_STORAGE_KEY, } from "./social.js";

package/dist/issuer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The issuer must be exactly one origin (`new URL(s).origin === s`): no trailing slash, no path, and nothing that URL
+ * normalization would rewrite (case, default port), because the token's `iss` is compared to it verbatim.
+ */
+export declare function normalizeIssuer(s: unknown): string;
+/** jwksUrl may have any path, but its origin follows the same rule as the issuer. Returns the normalized href (used as cache key). */
+export declare function normalizeJwksUrl(s: unknown): string;

package/dist/issuer.js

@@ -0,0 +1,37 @@
+import { RelytAuthError } from "./errors.js";
+/** Plain http is only accepted for exact loopback host names (local development); everything else must be https. */
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+function checkOrigin(u, option) {
+    if (u.protocol === "https:")
+        return;
+    if (u.protocol === "http:" && LOOPBACK.has(u.hostname))
+        return;
+    throw new RelytAuthError("config", { option });
+}
+function parse(s, option) {
+    if (typeof s !== "string" || s === "")
+        throw new RelytAuthError("config", { option });
+    try {
+        return new URL(s);
+    }
+    catch {
+        throw new RelytAuthError("config", { option });
+    }
+}
+/**
+ * The issuer must be exactly one origin (`new URL(s).origin === s`): no trailing slash, no path, and nothing that URL
+ * normalization would rewrite (case, default port), because the token's `iss` is compared to it verbatim.
+ */
+export function normalizeIssuer(s) {
+    const u = parse(s, "issuer");
+    if (u.origin !== s)
+        throw new RelytAuthError("config", { option: "issuer" });
+    checkOrigin(u, "issuer");
+    return u.origin;
+}
+/** jwksUrl may have any path, but its origin follows the same rule as the issuer. Returns the normalized href (used as cache key). */
+export function normalizeJwksUrl(s) {
+    const u = parse(s, "jwksUrl");
+    checkOrigin(u, "jwksUrl");
+    return u.href;
+}

package/dist/jwt-payload.d.ts

@@ -0,0 +1,2 @@
+/** Three non-empty segments and a base64url UTF-8 JSON object payload ⇒ that object; otherwise null. Never throws. */
+export declare function decodePayloadUnverified(token: string): Record<string, unknown> | null;

package/dist/jwt-payload.js

@@ -0,0 +1,21 @@
+// Reads a JWT payload without verifying it (shared by client.ts and next.ts).
+// Only for local hints such as lifetime / Max-Age; trust decisions must go through verifyToken. Web APIs only (edge / browser).
+/** Three non-empty segments and a base64url UTF-8 JSON object payload ⇒ that object; otherwise null. Never throws. */
+export function decodePayloadUnverified(token) {
+    if (typeof token !== "string")
+        return null;
+    const parts = token.split(".");
+    if (parts.length !== 3 || parts.some((p) => p === ""))
+        return null;
+    try {
+        const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const bin = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
+        const payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(bin, (c) => c.charCodeAt(0))));
+        if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/next.d.ts

@@ -0,0 +1,47 @@
+import { NextResponse, type NextRequest } from "next/server.js";
+import { RelytAuthError } from "./errors.js";
+import { type VerifierOptions } from "./verify.js";
+import type { RelytClaims } from "./claims.js";
+/** Default cookie name shared by the middleware, getClaims and set/clearTokenCookie. */
+export declare const DEFAULT_COOKIE_NAME = "__Host-relyt-at";
+export interface AuthMiddlewareOptions extends VerifierOptions {
+    /** Sign-in page; absolute URLs are used as-is, relative paths are resolved against the request URL. */
+    signInUrl: string;
+    /** Strings match by path-segment prefix; RegExps are tested against the pathname. */
+    publicPaths?: Array<string | RegExp>;
+    /** Default "/api/". */
+    apiPrefix?: string;
+    /** Default "__Host-relyt-at". */
+    cookieName?: string;
+    /** Default true; false ⇒ API paths accept bearer tokens only. */
+    cookieOnApi?: boolean;
+}
+/** JWKS unavailable (code "jwks_unavailable"): handlers should answer 503. */
+export declare class RelytAuthUnavailableError extends RelytAuthError {
+    constructor();
+}
+/**
+ * Normalizes `next`: decode first (failure ⇒ "/"); after decoding, any C0 control character / DEL (URL parsing strips \t\n\r, so "/\t/evil.com" would become "//evil.com"; spaces are allowed since the origin check below still applies),
+ * a leading // or /\, any \, no leading /, or a cross-origin result when resolved against a placeholder origin ⇒ "/".
+ */
+export declare function safeNext(pathAndSearch: string): string;
+export declare function createAuthMiddleware(o: AuthMiddlewareOptions): (req: NextRequest) => Promise<NextResponse>;
+/**
+ * Reads claims in a route handler: takes the token from the bearer header (preferred) or the cookie and verifies it again; never reads x-relyt-*.
+ * `cookie` defaults to true; false ⇒ Authorization only (matches the middleware's `cookieOnApi: false`).
+ * Missing / invalid / other-tenant token ⇒ null; JWKS unavailable ⇒ throws RelytAuthUnavailableError by default, `onUnavailable: "null"` ⇒ null.
+ */
+export declare function getClaims(req: Request, o: VerifierOptions & {
+    cookieName?: string;
+}, opts?: {
+    onUnavailable?: "throw" | "null";
+    cookie?: boolean;
+}): Promise<RelytClaims | null>;
+/** Writes the token cookie: Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=min(TOKEN_TTL_S, exp − now); remaining ≤ 0 ⇒ clears it instead. */
+export declare function setTokenCookie(res: NextResponse, token: string, o?: {
+    cookieName?: string;
+}): void;
+/** Clears the token cookie (sign-out must call this server-side: the cookie is HttpOnly, browser JS cannot clear it). */
+export declare function clearTokenCookie(res: NextResponse, o?: {
+    cookieName?: string;
+}): void;

package/dist/next.js

@@ -0,0 +1,205 @@
+// @relyt/auth/next: Next.js middleware entry. Web APIs + next/server only, usable in the edge runtime.
+// Security notes:
+// - The issuer comes only from configuration (options.issuer), never from the request's Host / X-Forwarded-Host; token iss/aud are compared to it verbatim.
+// - Incoming x-relyt-* headers are always stripped, on success or failure; the middleware never forwards claim headers, route handlers re-verify with getClaims.
+// - Tokens and cookie values never reach logs, responses or events.
+import { NextResponse } from "next/server.js";
+import { TOKEN_TTL_S } from "./constants.js";
+import { RelytAuthError } from "./errors.js";
+import { normalizeIssuer } from "./issuer.js";
+import { decodePayloadUnverified } from "./jwt-payload.js";
+import { createVerifier, verifyToken } from "./verify.js";
+/** Default cookie name shared by the middleware, getClaims and set/clearTokenCookie. */
+export const DEFAULT_COOKIE_NAME = "__Host-relyt-at";
+const STRIP_PREFIX = "x-relyt-";
+/** Auth failure responses are never cacheable, so a shared cache cannot replay a 401 / redirect / 503 to a signed-in user. */
+const NO_STORE = "no-store";
+/** JWKS unavailable (code "jwks_unavailable"): handlers should answer 503. */
+export class RelytAuthUnavailableError extends RelytAuthError {
+    constructor() {
+        super("jwks_unavailable");
+        this.name = "RelytAuthUnavailableError";
+    }
+}
+function bearer(h) {
+    const v = h.get("authorization");
+    if (v === null)
+        return null;
+    const m = /^Bearer[ ]+(\S+)[ ]*$/i.exec(v);
+    return m ? m[1] : null;
+}
+/** The cookie value if the name occurs exactly once in the Cookie header; multiple occurrences ⇒ null (prevents shadowing via cookies injected from a sibling subdomain). */
+function cookie(h, name) {
+    const raw = h.get("cookie");
+    if (raw === null)
+        return null;
+    const hits = [];
+    for (const part of raw.split(";")) {
+        const i = part.indexOf("=");
+        if (i < 0)
+            continue;
+        if (part.slice(0, i).trim() === name)
+            hits.push(part.slice(i + 1).trim());
+    }
+    if (hits.length !== 1 || hits[0] === "")
+        return null;
+    return hits[0];
+}
+/** A present Authorization header is authoritative: non-Bearer / malformed ⇒ no token, with no fallback to the cookie. */
+function readToken(h, name, allowCookie) {
+    if (h.has("authorization"))
+        return bearer(h);
+    return allowCookie ? cookie(h, name) : null;
+}
+function cookieNameOf(v) {
+    if (v === undefined)
+        return DEFAULT_COOKIE_NAME;
+    if (typeof v !== "string" || !/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(v))
+        throw new RelytAuthError("config", { option: "cookieName" });
+    return v;
+}
+/**
+ * Normalizes `next`: decode first (failure ⇒ "/"); after decoding, any C0 control character / DEL (URL parsing strips \t\n\r, so "/\t/evil.com" would become "//evil.com"; spaces are allowed since the origin check below still applies),
+ * a leading // or /\, any \, no leading /, or a cross-origin result when resolved against a placeholder origin ⇒ "/".
+ */
+export function safeNext(pathAndSearch) {
+    let d;
+    try {
+        d = decodeURIComponent(pathAndSearch);
+    }
+    catch {
+        return "/";
+    }
+    if (/[\x00-\x1f\x7f]/.test(d))
+        return "/";
+    if (!d.startsWith("/") || d.startsWith("//") || d.includes("\\"))
+        return "/";
+    try {
+        if (new URL(d, "https://n.invalid").origin !== "https://n.invalid")
+            return "/";
+    }
+    catch {
+        return "/";
+    }
+    return pathAndSearch;
+}
+function segPrefix(path, p) {
+    const base = p.endsWith("/") ? p.slice(0, -1) : p;
+    if (base === "")
+        return path === "/"; // "/" means the root path only, not "every path"
+    return path === base || path.startsWith(base + "/");
+}
+function isPublic(path, list) {
+    return list.some((p) => (typeof p === "string" ? segPrefix(path, p) : new RegExp(p.source, p.flags.replace(/[gy]/g, "")).test(path)));
+}
+export function createAuthMiddleware(o) {
+    if (typeof o !== "object" || o === null)
+        throw new RelytAuthError("config", { option: "issuer" });
+    normalizeIssuer(o.issuer);
+    const verify = createVerifier(o);
+    if (typeof o.signInUrl !== "string" || o.signInUrl === "")
+        throw new RelytAuthError("config", { option: "signInUrl" });
+    try {
+        new URL(o.signInUrl, "https://placeholder.invalid");
+    }
+    catch {
+        throw new RelytAuthError("config", { option: "signInUrl" });
+    }
+    const signInUrl = o.signInUrl;
+    const apiPrefix = o.apiPrefix ?? "/api/";
+    if (typeof apiPrefix !== "string" || !apiPrefix.startsWith("/"))
+        throw new RelytAuthError("config", { option: "apiPrefix" });
+    /** "/api/" also covers the bare path "/api". */
+    const apiBare = apiPrefix.length > 1 && apiPrefix.endsWith("/") ? apiPrefix.slice(0, -1) : null;
+    const cookieName = cookieNameOf(o.cookieName);
+    const cookieOnApi = o.cookieOnApi ?? true;
+    const publicPaths = o.publicPaths ?? [];
+    return async (req) => {
+        const headers = new Headers();
+        req.headers.forEach((v, k) => {
+            if (!k.toLowerCase().startsWith(STRIP_PREFIX))
+                headers.set(k, v);
+        });
+        const pass = () => NextResponse.next({ request: { headers } });
+        const path = req.nextUrl.pathname;
+        if (isPublic(path, publicPaths))
+            return pass();
+        const api = path.startsWith(apiPrefix) || path === apiBare || (req.headers.get("accept") ?? "").toLowerCase().includes("application/json");
+        const token = readToken(req.headers, cookieName, !api || cookieOnApi);
+        let failure = "none";
+        if (token !== null) {
+            try {
+                await verify(token);
+                return pass();
+            }
+            catch (e) {
+                failure = e instanceof RelytAuthError && e.code === "jwks_unavailable" ? "unavailable" : "invalid";
+            }
+        }
+        if (failure === "unavailable") {
+            return NextResponse.json({ error: "auth_unavailable" }, { status: 503, headers: { "retry-after": "2", "cache-control": NO_STORE } });
+        }
+        if (api) {
+            const www = failure === "none" ? "Bearer" : 'Bearer error="invalid_token"';
+            return NextResponse.json({ error: "unauthorized" }, { status: 401, headers: { "www-authenticate": www, "cache-control": NO_STORE } });
+        }
+        const target = new URL(signInUrl, req.nextUrl.href);
+        target.searchParams.set("next", safeNext(path + req.nextUrl.search));
+        const method = req.method.toUpperCase();
+        const res = NextResponse.redirect(target, method === "GET" || method === "HEAD" ? 307 : 303);
+        res.headers.set("cache-control", NO_STORE);
+        return res;
+    };
+}
+/**
+ * Reads claims in a route handler: takes the token from the bearer header (preferred) or the cookie and verifies it again; never reads x-relyt-*.
+ * `cookie` defaults to true; false ⇒ Authorization only (matches the middleware's `cookieOnApi: false`).
+ * Missing / invalid / other-tenant token ⇒ null; JWKS unavailable ⇒ throws RelytAuthUnavailableError by default, `onUnavailable: "null"` ⇒ null.
+ */
+export async function getClaims(req, o, opts = {}) {
+    const token = readToken(req.headers, cookieNameOf(o?.cookieName), opts.cookie ?? true);
+    if (token === null) {
+        normalizeIssuer(o?.issuer); // validate the config even without a token, so a misconfiguration is not hidden behind null
+        return null;
+    }
+    try {
+        return await verifyToken(token, o);
+    }
+    catch (e) {
+        if (!(e instanceof RelytAuthError))
+            throw e;
+        if (e.code === "jwks_unavailable") {
+            if ((opts.onUnavailable ?? "throw") === "null")
+                return null;
+            throw new RelytAuthUnavailableError();
+        }
+        if (e.code === "invalid_token" || e.code === "invalid_claims")
+            return null;
+        throw e;
+    }
+}
+/** Reads the payload `exp` only (no verification: the cookie is written by the server that just obtained the token, Max-Age is only a lifetime cap). */
+function expOf(token) {
+    const exp = decodePayloadUnverified(token)?.exp;
+    return typeof exp === "number" && Number.isFinite(exp) ? exp : null;
+}
+const MAX_COOKIE_BYTES = 4000;
+const COOKIE_ATTRS = { path: "/", secure: true, httpOnly: true, sameSite: "lax" };
+/** Writes the token cookie: Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=min(TOKEN_TTL_S, exp − now); remaining ≤ 0 ⇒ clears it instead. */
+export function setTokenCookie(res, token, o = {}) {
+    const name = cookieNameOf(o.cookieName);
+    const exp = expOf(token);
+    const left = exp === null ? 0 : Math.floor(exp - Date.now() / 1000);
+    if (left <= 0)
+        return clearTokenCookie(res, o);
+    const maxAge = Math.min(TOKEN_TTL_S, left);
+    // Browsers cap a single cookie at about 4096 bytes and silently drop larger ones ⇒ sign-in "succeeds" but no token ever arrives; fail loudly on the server instead.
+    const serialized = `${name}=${token}; Path=/; Max-Age=${maxAge}; Secure; HttpOnly; SameSite=Lax`;
+    if (new TextEncoder().encode(serialized).length > MAX_COOKIE_BYTES)
+        throw new RelytAuthError("config", { option: "cookieSize" });
+    res.cookies.set(name, token, { ...COOKIE_ATTRS, maxAge });
+}
+/** Clears the token cookie (sign-out must call this server-side: the cookie is HttpOnly, browser JS cannot clear it). */
+export function clearTokenCookie(res, o = {}) {
+    res.cookies.set(cookieNameOf(o.cookieName), "", { ...COOKIE_ATTRS, maxAge: 0 });
+}

package/dist/options.d.ts

@@ -0,0 +1,2 @@
+/** Numeric option: undefined ⇒ dflt; non-finite or failing `ok` ⇒ `config` (carries the option name only, never the value). */
+export declare function num(v: unknown, dflt: number, option: string, ok: (n: number) => boolean): number;

package/dist/options.js

@@ -0,0 +1,10 @@
+// Shared option validation (used by verify.ts, client.ts and social.ts).
+import { RelytAuthError } from "./errors.js";
+/** Numeric option: undefined ⇒ dflt; non-finite or failing `ok` ⇒ `config` (carries the option name only, never the value). */
+export function num(v, dflt, option, ok) {
+    if (v === undefined)
+        return dflt;
+    if (typeof v !== "number" || !Number.isFinite(v) || !ok(v))
+        throw new RelytAuthError("config", { option });
+    return v;
+}

package/dist/social.d.ts

@@ -0,0 +1,54 @@
+import { type AuthClient } from "./client.js";
+/** sessionStorage key: one pending sign-in record `{v, mode, base, t}` (single use, removed when read by complete). */
+export declare const SOCIAL_PKCE_STORAGE_KEY = "relyt.auth.social.pkce";
+export type SocialResponseMode = "fragment" | "query";
+export interface StartSocialSignInOptions {
+    /** `https://<authHost>`, same rules as createAuthClient. */
+    authUrl: string;
+    provider: string;
+    /** Must match the callback URL registered in the console verbatim (exact match, no wildcards). */
+    callbackURL: string;
+    errorCallbackURL?: string;
+    newUserCallbackURL?: string;
+    /** Default fragment (the code never reaches server logs / Referer). */
+    responseMode?: SocialResponseMode;
+}
+export interface CompleteSocialSignInOptions {
+    authUrl: string;
+    /** Called with the session token (bearer mode); the app stores it and provides it via createAuthClient's sessionToken. */
+    onSessionToken: (t: string) => void;
+    /** Given ⇒ clear() is called before delivering the new token, dropping JWTs cached for the previous identity. */
+    client?: AuthClient;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+export interface ExchangeHandoffCodeOptions {
+    authUrl: string;
+    code: string;
+    codeVerifier: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+export interface SocialStart {
+    /** Full URL of the auth host's sign-in start endpoint (navigate the top-level window to it). */
+    url: string;
+    /** PKCE verifier; submitted verbatim on exchange, never logged. */
+    codeVerifier: string;
+}
+/**
+ * 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 declare function createSocialStart(o: StartSocialSignInOptions): Promise<SocialStart>;
+/** Browser entry: build → store the pending record → navigate the top-level window to the auth host. */
+export declare function startSocialSignIn(o: StartSocialSignInOptions): Promise<void>;
+/**
+ * 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 declare function completeSocialSignIn(o: CompleteSocialSignInOptions): Promise<void>;
+/** Server-side proxy (Node / Next route handler): no Origin header, exchanges directly. */
+export declare function exchangeHandoffCode(o: ExchangeHandoffCodeOptions): Promise<{
+    sessionToken: string;
+}>;