@andco/sdk 0.0.2 → 0.0.4

package/dist/tokens.js

@@ -0,0 +1,148 @@
+import { decodeJwtPayload } from "@andco/protocol";
+import { AndcoError, Result } from "./errors.js";
+import { andcoServerMetadata } from "./server-metadata.generated.js";
+const ALGORITHMS = {
+    RS256: {
+        import: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+        verify: { name: "RSASSA-PKCS1-v1_5" },
+    },
+    ES256: {
+        import: { name: "ECDSA", namedCurve: "P-256" },
+        verify: { name: "ECDSA", hash: "SHA-256" },
+    },
+};
+/** Minimum time between two JWKS downloads triggered by an unknown `kid`, so a bad token cannot hammer the server. */
+const JWKS_REFRESH_COOLDOWN_MS = 10_000;
+/**
+ * Offline verification of Andco access tokens with the Authorization Server's JWKS.
+ *
+ * The JWKS URL comes from the baked Server Description, re-rooted on the configured issuer, and
+ * keys are cached by `kid`. An unknown `kid` triggers one (rate limited) refetch, which is how a key
+ * rotation is picked up without a restart. A valid signature proves who issued the token, not that
+ * the Grant behind it is still alive: use `grants.get` for that.
+ *
+ * @example
+ * ```ts
+ * const { data: claims, error } = await andco.tokens.verify(bearer, { audience: "https://api.casa-norte.example" });
+ * if (error) return new Response(null, { status: 401 });
+ * ```
+ */
+export class AndcoTokens {
+    #config;
+    #globals;
+    #keys = new Map();
+    #fetchedAt = 0;
+    #loading = null;
+    constructor(options) {
+        this.#config = options.config;
+        this.#globals = options.globals;
+    }
+    /** The `iss` the Authorization Server signs: the configured base URL without a trailing slash. */
+    get issuer() {
+        const base = this.#config.endpoints.auth;
+        return `${base.origin}${base.pathname.replace(/\/+$/, "")}`;
+    }
+    /** Checks signature, `exp`, `iss` and, when given, `aud`. Never throws. */
+    async verify(token, options = {}) {
+        const fail = (code, message, cause) => {
+            console.debug("[tokens.verify] rejected %s: %s", code, message);
+            return Result.fail(new AndcoError(code, { message, cause }));
+        };
+        try {
+            const parts = token.split(".");
+            const header = parts.length === 3 ? parseHeader(parts[0]) : null;
+            if (!header)
+                return fail("invalid_token", "token is not a JWT");
+            const algorithm = header.alg;
+            if (typeof header.alg !== "string" || !Object.hasOwn(ALGORITHMS, header.alg)) {
+                return fail("invalid_token", `unsupported signing algorithm ${String(header.alg)}`);
+            }
+            const signing = await this.#keyFor(typeof header.kid === "string" ? header.kid : undefined, algorithm);
+            if (!signing)
+                return fail("invalid_token", "no JWKS key matches the token kid");
+            const valid = await globalThis.crypto.subtle.verify(ALGORITHMS[algorithm].verify, signing.key, bytes(parts[2]), new TextEncoder().encode(`${parts[0]}.${parts[1]}`));
+            if (!valid)
+                return fail("invalid_token", "signature does not verify");
+            const claims = decodeJwtPayload(token);
+            if (!claims)
+                return fail("invalid_token", "payload is not a JSON object");
+            const tolerance = options.clockToleranceSeconds ?? 30;
+            const now = Math.floor(Date.now() / 1000);
+            if (typeof claims["exp"] !== "number")
+                return fail("invalid_token", "exp claim is missing");
+            if (claims["exp"] + tolerance <= now)
+                return fail("invalid_token", "token is expired");
+            if (typeof claims["nbf"] === "number" && claims["nbf"] - tolerance > now) {
+                return fail("invalid_token", "token is not yet valid");
+            }
+            if (claims["iss"] !== this.issuer)
+                return fail("invalid_token", "issuer does not match the configured one");
+            if (options.audience !== undefined) {
+                const aud = claims["aud"];
+                const audiences = typeof aud === "string" ? [aud] : Array.isArray(aud) ? aud : [];
+                if (!audiences.includes(options.audience))
+                    return fail("invalid_token", "audience does not match");
+            }
+            console.debug("[tokens.verify] accepted sub=%s", claims["sub"]);
+            return Result.ok(claims);
+        }
+        catch (cause) {
+            return fail("invalid_token", "verification failed", cause);
+        }
+    }
+    async #keyFor(kid, algorithm) {
+        const lookup = () => (kid === undefined ? this.#onlyKey() : this.#keys.get(kid));
+        const cached = lookup();
+        if (cached)
+            return cached;
+        if (Date.now() - this.#fetchedAt < JWKS_REFRESH_COOLDOWN_MS && this.#fetchedAt > 0)
+            return null;
+        this.#loading ??= this.#refresh(algorithm).finally(() => {
+            this.#loading = null;
+        });
+        await this.#loading;
+        return lookup() ?? null;
+    }
+    #onlyKey() {
+        return this.#keys.size === 1 ? [...this.#keys.values()][0] : undefined;
+    }
+    async #refresh(algorithm) {
+        this.#fetchedAt = Date.now();
+        const uri = andcoServerMetadata(this.issuer).jwks_uri;
+        console.debug("[tokens.refresh] fetching JWKS %s", uri);
+        const response = await this.#globals.fetch(uri, { headers: { Accept: "application/json" } });
+        if (!response.ok)
+            throw new AndcoError("jwks_unavailable", { message: `JWKS answered ${response.status}` });
+        const body = (await response.json());
+        const next = new Map();
+        for (const jwk of body.keys ?? []) {
+            if (!jwk.kid || (jwk.use && jwk.use !== "sig"))
+                continue;
+            const alg = (jwk.alg ?? (jwk.kty === "EC" ? "ES256" : "RS256"));
+            if (!Object.hasOwn(ALGORITHMS, alg))
+                continue;
+            const key = await globalThis.crypto.subtle.importKey("jwk", jwk, ALGORITHMS[alg].import, false, ["verify"]);
+            next.set(jwk.kid, { key, algorithm: ALGORITHMS[alg].import });
+        }
+        this.#keys.clear();
+        for (const [kid, key] of next)
+            this.#keys.set(kid, key);
+        console.debug("[tokens.refresh] cached kids %o for %s", [...next.keys()], algorithm);
+    }
+}
+function bytes(segment) {
+    const base64 = segment
+        .replace(/-/g, "+")
+        .replace(/_/g, "/")
+        .padEnd(Math.ceil(segment.length / 4) * 4, "=");
+    return Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+}
+function parseHeader(segment) {
+    try {
+        const header = JSON.parse(new TextDecoder().decode(bytes(segment)));
+        return header && typeof header === "object" && !Array.isArray(header) ? header : null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andco/sdk",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -33,8 +33,8 @@
     "dist"
   ],
   "dependencies": {
-    "@andco/openapi-fetch": "0.0.1",
-    "@andco/protocol": "0.0.1",
+    "@andco/openapi-fetch": "0.0.4",
+    "@andco/protocol": "0.0.4",
     "openid-client": "^6.8.8"
   },
   "devDependencies": {
@@ -43,6 +43,16 @@
   },
   "license": "Apache-2.0",
   "description": "Andco SDK: OAuth authorization, sessions and API access for browser and server.",
+  "author": "Patricio Lopez Juri <patricio.lopez@haulmer.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haulmer/andco-sdk-js.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/haulmer/andco-sdk-js#readme",
+  "bugs": {
+    "url": "https://github.com/haulmer/andco-sdk-js/issues"
+  },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "pnpm run clean && tsc",