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

package/dist/validator/validator.js

@@ -0,0 +1,197 @@
+/**
+ * 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, decodeProtectedHeader } from "jose";
+import * as errors from "./errors.js";
+import { normaliseType, resolveConfig, } from "./config.js";
+import { jsonOk, request } from "../http.js";
+import { JwksProvider } from "./jwks.js";
+import { failure, success } from "./result.js";
+const defaultPost = async (url, body, headers) => {
+    // the shared transport never follows a redirect: it would carry the resource server's credentials
+    const resp = await request(url, { method: "POST", body, headers, timeoutMs: 10_000 });
+    if (!resp.ok) {
+        throw new Error(`introspection failed: ${resp.status}`);
+    }
+    return jsonOk(resp);
+};
+/** Validates access tokens for a resource server. */
+export class AccessTokenValidator {
+    config;
+    #jwks;
+    #httpPost;
+    constructor(config, opts = {}) {
+        this.config = resolveConfig(config);
+        this.#jwks = new JwksProvider({
+            jwks: this.config.jwks,
+            jwksUri: this.config.jwksUri,
+            httpGet: opts.httpGet,
+        });
+        this.#httpPost = opts.httpPost ?? defaultPost;
+    }
+    /**
+     * 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) {
+        const required = requiredScopes ?? this.config.requiredScopes;
+        let header;
+        try {
+            header = decodeProtectedHeader(token);
+        }
+        catch (exc) {
+            return failure(errors.INVALID_TOKEN, `malformed token: ${errMessage(exc)}`);
+        }
+        const alg = header.alg;
+        if (alg == null || !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 key = await this.#jwks.resolve(header.kid, alg);
+        if (key == null) {
+            return failure(errors.KEY_NOT_FOUND, this.#jwks.lastError ?? "no signing key for this kid");
+        }
+        let claims;
+        try {
+            const { payload } = await compactVerify(token, key, { algorithms: [alg] });
+            claims = JSON.parse(new TextDecoder().decode(payload));
+        }
+        catch (exc) {
+            return failure(errors.INVALID_SIGNATURE, errMessage(exc));
+        }
+        if (claims === null || typeof claims !== "object" || Array.isArray(claims)) {
+            return failure(errors.INVALID_TOKEN, "payload is not a JSON object");
+        }
+        const types = this.config.acceptedTokenTypes;
+        if (header.typ != null && types !== null && !types.includes(normaliseType(String(header.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(Date.now() / 1000);
+        const leeway = this.config.leewaySeconds;
+        let exp;
+        let nbf;
+        let iat;
+        try {
+            exp = numericDate(claims, "exp");
+            nbf = numericDate(claims, "nbf");
+            iat = 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");
+        }
+        const audience = asList(claims.aud);
+        if (!this.config.audiences.some((a) => audience.includes(a))) {
+            return failure(errors.INVALID_AUDIENCE, "token audience is not accepted");
+        }
+        const granted = scopesOf(claims);
+        const missing = required.filter((s) => !granted.includes(s));
+        if (missing.length > 0) {
+            return failure(errors.INSUFFICIENT_SCOPE, `missing scopes: ${missing.join(" ")}`);
+        }
+        return success(claims, granted, audience);
+    }
+    /**
+     * 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);
+        }
+        return this.#httpPost(cfg.endpoint, form.toString(), headers);
+    }
+    /**
+     * Introspect the token and enforce `active` plus scope/audience from the response.
+     */
+    async validateActive(token, requiredScopes) {
+        const data = await this.introspect(token);
+        if (!data.active) {
+            return failure(errors.INACTIVE, "token is not active");
+        }
+        const required = requiredScopes ?? this.config.requiredScopes;
+        const granted = scopesOf(data);
+        const missing = required.filter((s) => !granted.includes(s));
+        if (missing.length > 0) {
+            return failure(errors.INSUFFICIENT_SCOPE, `missing scopes: ${missing.join(" ")}`);
+        }
+        const audience = asList(data.aud);
+        if (this.config.audiences.length > 0 &&
+            audience.length > 0 &&
+            !this.config.audiences.some((a) => audience.includes(a))) {
+            return failure(errors.INVALID_AUDIENCE, "token audience is not accepted");
+        }
+        return success(data, granted, audience);
+    }
+}
+/** A NumericDate claim as an integer, `undefined` when absent. Anything but a finite number is malformed. */
+function numericDate(claims, name) {
+    const value = claims[name];
+    if (value == null) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${name} is not a NumericDate`);
+    }
+    return Math.trunc(value);
+}
+/** Normalize an `aud` claim (string | string[] | absent) to a list of strings. */
+function asList(value) {
+    if (value == null) {
+        return [];
+    }
+    return Array.isArray(value) ? value.map(String) : [String(value)];
+}
+/** Granted scopes from `scope` (space-delimited string) or `scp` (array). */
+function scopesOf(claims) {
+    const scope = claims.scope;
+    if (typeof scope === "string") {
+        return scope.split(/\s+/).filter((s) => s.length > 0);
+    }
+    const scp = claims.scp;
+    if (Array.isArray(scp)) {
+        return scp.map(String);
+    }
+    return [];
+}
+function base64(value) {
+    return Buffer.from(value, "utf8").toString("base64");
+}
+function errMessage(exc) {
+    return exc instanceof Error ? exc.message : String(exc);
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@idpartners/client-attestation-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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",
+    "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.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}