@idpartners/client-attestation-sdk 0.0.0-stage → 1.0.0

package/dist/validator/validator.js

@@ -0,0 +1,240 @@
+/**
+ * Access-token validation: JWT signature + claim checks, and optional RFC 7662 introspection.
+ *
+ * `validate` does local JWT validation in a fixed order — algorithm accepted, key resolvable,
+ * signature, `typ` (when present), `iss`, `exp` present, `exp`, `nbf`, `iat` not in the future, audience,
+ * then scope — returning the first failure's stable error code. That order is part of the cross-language contract so every port reports the same verdict.
+ * `validateActive` instead uses RFC 7662 introspection.
+ */
+import { compactVerify } from "jose";
+import { base64Encode, utf8Encode } from "../runtime.js";
+import * as errors from "./errors.js";
+import * as strict from "./strict.js";
+import { isForbiddenAlgorithm, normaliseType, resolveConfig, } from "./config.js";
+import { TransportError } from "../errors.js";
+import { request } from "../http.js";
+import { emit, failureReason, NOOP_LOGGER, urlParts } from "../logging.js";
+import { JwksProvider } from "./jwks.js";
+import { failure, success } from "./result.js";
+/**
+ * An introspection response larger than this is refused.
+ *
+ * @internal
+ */
+export const MAX_INTROSPECTION_BYTES = 1024 * 1024;
+const defaultPost = async (url, body, headers) => {
+    // the shared transport never follows a redirect (it would carry the resource server's credentials) and
+    // refuses a body over the cap
+    const resp = await request(url, {
+        method: "POST",
+        body,
+        headers,
+        timeoutMs: 10_000,
+        maxBytes: MAX_INTROSPECTION_BYTES,
+    });
+    if (!resp.ok) {
+        throw new TransportError(`introspection failed: ${resp.status}`, "status", { status: resp.status });
+    }
+    try {
+        return strict.parseObject(utf8Encode(resp.body), "introspection response");
+    }
+    catch (err) {
+        throw new TransportError(`introspection endpoint returned ${errMessage(err)}`, "json", {
+            status: resp.status,
+        });
+    }
+};
+/** Validates access tokens for a resource server. */
+export class AccessTokenValidator {
+    config;
+    #jwks;
+    #httpPost;
+    #logger;
+    #clock;
+    constructor(config, opts = {}) {
+        this.config = resolveConfig(config);
+        this.#jwks = new JwksProvider({
+            jwks: this.config.jwks,
+            jwksUri: this.config.jwksUri,
+            httpGet: opts.httpGet,
+            logger: opts.logger,
+        });
+        this.#httpPost = opts.httpPost ?? defaultPost;
+        this.#logger = opts.logger ?? NOOP_LOGGER;
+        this.#clock = opts.clock ?? Date.now;
+    }
+    /**
+     * Locally validate a JWT access token. Returns the first failure in the fixed contract order, or a
+     * success result exposing subject / scopes / audience / claims.
+     */
+    async validate(token, requiredScopes) {
+        return this.#verdict("jwt", await this.#validate(token, requiredScopes));
+    }
+    /** Log a verdict (its error code only, never the token) and return it. */
+    #verdict(mode, result) {
+        emit(this.#logger, result.valid ? "debug" : "info", "token.validated", { result: result.valid ? "valid" : result.error, mode });
+        return result;
+    }
+    async #validate(token, requiredScopes) {
+        const required = requiredScopes ?? this.config.requiredScopes;
+        let parts;
+        try {
+            parts = strict.splitCompact(token);
+        }
+        catch {
+            // never echo token data to the caller: the description lands in WWW-Authenticate
+            return failure(errors.INVALID_TOKEN, "malformed token");
+        }
+        const { header } = parts;
+        const alg = header.alg;
+        if (typeof alg !== "string" || isForbiddenAlgorithm(alg) || !this.config.acceptedAlgorithms.includes(alg)) {
+            // never echo the unverified header alg back to the caller (it lands in WWW-Authenticate)
+            return failure(errors.UNSUPPORTED_ALGORITHM, "algorithm not accepted");
+        }
+        const kid = header.kid;
+        const key = kid == null || typeof kid === "string" ? await this.#jwks.resolve(kid ?? undefined, alg) : null;
+        if (key == null) {
+            return failure(errors.KEY_NOT_FOUND, this.#jwks.lastError ?? "no signing key for this kid");
+        }
+        try {
+            await compactVerify(token, key, { algorithms: [alg] });
+        }
+        catch {
+            return failure(errors.INVALID_SIGNATURE, "signature verification failed");
+        }
+        let claims;
+        try {
+            claims = strict.parseObject(parts.payload);
+        }
+        catch (exc) {
+            return failure(errors.INVALID_TOKEN, errMessage(exc));
+        }
+        const types = this.config.acceptedTokenTypes;
+        const typ = header.typ;
+        if (typ != null && types !== null && (typeof typ !== "string" || !types.includes(normaliseType(typ)))) {
+            return failure(errors.INVALID_TOKEN_TYPE, "token is not a JWT access token");
+        }
+        if (claims.iss !== this.config.issuer) {
+            return failure(errors.INVALID_ISSUER, "unexpected issuer");
+        }
+        const now = Math.floor(this.#clock() / 1000);
+        const leeway = this.config.leewaySeconds;
+        let exp;
+        let nbf;
+        let iat;
+        try {
+            exp = strict.numericDate(claims, "exp");
+            nbf = strict.numericDate(claims, "nbf");
+            iat = strict.numericDate(claims, "iat");
+        }
+        catch (exc) {
+            return failure(errors.INVALID_TOKEN, errMessage(exc));
+        }
+        if (exp === undefined) {
+            return failure(errors.MISSING_EXPIRY, "token has no exp claim");
+        }
+        if (now > exp + leeway) {
+            return failure(errors.EXPIRED, "token has expired");
+        }
+        if (nbf !== undefined && now + leeway < nbf) {
+            return failure(errors.NOT_YET_VALID, "token is not yet valid");
+        }
+        if (iat !== undefined && now + leeway < iat) {
+            return failure(errors.ISSUED_IN_FUTURE, "token was issued in the future");
+        }
+        try {
+            const audience = strict.audience(claims);
+            if (!this.config.audiences.some((a) => audience.includes(a))) {
+                return failure(errors.INVALID_AUDIENCE, "token audience is not accepted");
+            }
+            const granted = strict.scopes(claims);
+            const missing = required.filter((s) => !granted.includes(s));
+            if (missing.length > 0) {
+                return failure(errors.INSUFFICIENT_SCOPE, `missing scopes: ${missing.join(" ")}`);
+            }
+            strict.subject(claims);
+            return success(claims, granted, audience);
+        }
+        catch (exc) {
+            return failure(errors.INVALID_TOKEN, errMessage(exc));
+        }
+    }
+    /**
+     * RFC 7662: POST the token to the AS introspection endpoint and return the parsed response.
+     */
+    async introspect(token, tokenTypeHint = "access_token") {
+        const cfg = this.config.introspection;
+        if (cfg == null) {
+            throw new Error("no introspection endpoint configured");
+        }
+        const form = new URLSearchParams();
+        form.set("token", token);
+        form.set("token_type_hint", tokenTypeHint);
+        const headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+        };
+        const authMethod = cfg.authMethod ?? "client_secret_basic";
+        if (authMethod === "client_secret_basic") {
+            const raw = `${cfg.clientId}:${cfg.clientSecret}`;
+            headers.Authorization = `Basic ${base64(raw)}`;
+        }
+        else {
+            form.set("client_id", cfg.clientId);
+            form.set("client_secret", cfg.clientSecret);
+        }
+        try {
+            const data = await this.#httpPost(cfg.endpoint, form.toString(), headers);
+            if (data === null || typeof data !== "object" || Array.isArray(data)) {
+                throw new TransportError("introspection endpoint returned JSON that is not an object", "json");
+            }
+            return data;
+        }
+        catch (err) {
+            emit(this.#logger, "warn", "http.failed", {
+                step: "introspection",
+                method: "POST",
+                ...urlParts(cfg.endpoint),
+                status: err instanceof TransportError ? err.status : undefined,
+                reason: failureReason(err),
+            });
+            throw err;
+        }
+    }
+    /**
+     * Introspect the token and enforce `active` plus scope/audience from the response.
+     */
+    async validateActive(token, requiredScopes) {
+        return this.#verdict("introspection", await this.#validateActive(token, requiredScopes));
+    }
+    async #validateActive(token, requiredScopes) {
+        const data = await this.introspect(token);
+        // RFC 7662 section 2.2: active is a boolean, so only JSON true counts
+        if (data.active !== true) {
+            return failure(errors.INACTIVE, "token is not active");
+        }
+        const required = requiredScopes ?? this.config.requiredScopes;
+        try {
+            const granted = strict.scopes(data);
+            const missing = required.filter((s) => !granted.includes(s));
+            if (missing.length > 0) {
+                return failure(errors.INSUFFICIENT_SCOPE, `missing scopes: ${missing.join(" ")}`);
+            }
+            const audience = strict.audience(data);
+            if (audience.length > 0 && !this.config.audiences.some((a) => audience.includes(a))) {
+                return failure(errors.INVALID_AUDIENCE, "token audience is not accepted");
+            }
+            strict.subject(data);
+            return success(data, granted, audience);
+        }
+        catch (exc) {
+            return failure(errors.INVALID_TOKEN, errMessage(exc));
+        }
+    }
+}
+function base64(value) {
+    return base64Encode(utf8Encode(value));
+}
+function errMessage(exc) {
+    return exc instanceof Error ? exc.message : String(exc);
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@idpartners/client-attestation-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Client-side builder SDK for OAuth Attestation-Based Client Authentication",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./validator": {
+      "types": "./dist/validator/index.d.ts",
+      "import": "./dist/validator/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "test:edge": "node test/edge/run-workerd.mjs",
+    "emit": "tsx emit.ts",
+    "validate-emit": "tsx validate-emit.ts"
+  },
+  "license": "Apache-2.0",
+  "author": "ID Partners Pty Ltd",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ID-Partners/client-attestation-sdk.git",
+    "directory": "typescript"
+  },
+  "homepage": "https://github.com/ID-Partners/client-attestation-sdk/tree/main/typescript",
+  "dependencies": {
+    "jose": "^6.2.12"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "esbuild": "^0.28.1",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "workerd": "1.20261007.1"
+  }
+}