@zauso-ai/capstan-auth 1.0.0-beta.5 → 1.0.0-beta.6

package/dist/dpop.d.ts

@@ -0,0 +1,46 @@
+import type { KeyValueStore } from "./store.js";
+/**
+ * Result of a successful DPoP proof validation.
+ */
+export interface DpopValidationResult {
+    /** Base64url-encoded JWK thumbprint (RFC 7638) of the proof key. */
+    thumbprint: string;
+}
+/**
+ * Replace the default in-memory DPoP replay store with a custom implementation.
+ *
+ * Call this at application startup before any DPoP proofs are validated.
+ */
+export declare function setDpopReplayStore(store: KeyValueStore<true>): void;
+/**
+ * Validate a DPoP proof JWT per RFC 9449.
+ *
+ * The proof is a compact-serialized JWT whose header contains the public key
+ * (`jwk`) used to sign the proof.  The function:
+ *
+ * 1. Parses the JOSE header and verifies `typ: "dpop+jwt"` and a supported `alg`.
+ * 2. Extracts the embedded `jwk` and imports it via Web Crypto.
+ * 3. Verifies the JWT signature using the imported key.
+ * 4. Validates required claims:
+ *    - `htm` — must match the provided HTTP method.
+ *    - `htu` — must match the provided HTTP URI (scheme + authority + path).
+ *    - `iat` — must be within the acceptable time window.
+ *    - `jti` — must be unique (checked against an in-memory replay cache).
+ * 5. If an `accessToken` is provided, verifies the `ath` (access token hash)
+ *    claim matches the SHA-256 hash of the token.
+ *
+ * Returns the JWK thumbprint on success, or `null` if validation fails.
+ *
+ * @param proof   - The DPoP proof from the `DPoP` request header.
+ * @param method  - The HTTP method of the request (e.g. "POST").
+ * @param url     - The full request URL.
+ * @param accessToken - Optional access token to verify `ath` binding.
+ */
+export declare function validateDpopProof(proof: string, method: string, url: string, accessToken?: string): Promise<DpopValidationResult | null>;
+/**
+ * Clear the DPoP JTI replay cache.
+ *
+ * Useful for tests so state does not leak between test cases.
+ */
+export declare function clearDpopReplayCache(): Promise<void>;
+//# sourceMappingURL=dpop.d.ts.map

package/dist/dpop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dpop.d.ts","sourceRoot":"","sources":["../src/dpop.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOhD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACpB;AAoBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAEnE;AAmGD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA4JtC;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1D"}

package/dist/dpop.js

@@ -0,0 +1,259 @@
+import { createHash } from "node:crypto";
+import { MemoryStore } from "./store.js";
+/** Maximum age (in seconds) for a DPoP proof's `iat` claim. */
+const MAX_PROOF_AGE_SECONDS = 300; // 5 minutes
+/** Minimum age (in seconds) — reject proofs from the far future. */
+const MAX_CLOCK_SKEW_SECONDS = 60;
+/** TTL for JTI replay cache entries (proof age + clock skew). */
+const JTI_TTL_MS = (MAX_PROOF_AGE_SECONDS + MAX_CLOCK_SKEW_SECONDS) * 1000;
+/**
+ * Pluggable store for tracking recently seen `jti` values to prevent replay.
+ *
+ * Each entry stores `true` as a sentinel value with a TTL equal to the proof
+ * window.  The `MemoryStore` default lazily expires entries on access; custom
+ * implementations (e.g. Redis) can use native TTL support.
+ */
+let dpopReplayStore = new MemoryStore();
+/**
+ * Replace the default in-memory DPoP replay store with a custom implementation.
+ *
+ * Call this at application startup before any DPoP proofs are validated.
+ */
+export function setDpopReplayStore(store) {
+    dpopReplayStore = store;
+}
+// ---------------------------------------------------------------------------
+// Base64url helpers
+// ---------------------------------------------------------------------------
+function base64urlDecode(str) {
+    // Convert base64url to standard base64.
+    let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+    // Pad with '=' to make length a multiple of 4.
+    while (base64.length % 4 !== 0) {
+        base64 += "=";
+    }
+    return Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+}
+function base64urlEncode(buffer) {
+    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    let binary = "";
+    for (const b of bytes) {
+        binary += String.fromCharCode(b);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+// ---------------------------------------------------------------------------
+// JWK Thumbprint (RFC 7638)
+// ---------------------------------------------------------------------------
+/**
+ * Compute the JWK thumbprint per RFC 7638.
+ *
+ * For RSA keys the required members are: e, kty, n
+ * For EC keys: crv, kty, x, y
+ */
+function computeJwkThumbprint(jwk) {
+    let canonicalMembers;
+    if (jwk.kty === "RSA") {
+        canonicalMembers = { e: jwk.e, kty: jwk.kty, n: jwk.n };
+    }
+    else if (jwk.kty === "EC") {
+        canonicalMembers = {
+            crv: jwk.crv,
+            kty: jwk.kty,
+            x: jwk.x,
+            y: jwk.y,
+        };
+    }
+    else {
+        throw new Error(`Unsupported key type: ${jwk.kty}`);
+    }
+    // Lexicographic ordering of keys (JSON Canonicalization is just sorted keys
+    // for the required members).
+    const sortedKeys = Object.keys(canonicalMembers).sort();
+    const json = "{" +
+        sortedKeys
+            .map((k) => `${JSON.stringify(k)}:${JSON.stringify(canonicalMembers[k])}`)
+            .join(",") +
+        "}";
+    const hash = createHash("sha256").update(json).digest();
+    return base64urlEncode(hash);
+}
+function mapAlgorithm(alg) {
+    switch (alg) {
+        case "RS256":
+            return { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" };
+        case "RS384":
+            return { name: "RSASSA-PKCS1-v1_5", hash: "SHA-384" };
+        case "RS512":
+            return { name: "RSASSA-PKCS1-v1_5", hash: "SHA-512" };
+        case "ES256":
+            return { name: "ECDSA", hash: "SHA-256", namedCurve: "P-256" };
+        case "ES384":
+            return { name: "ECDSA", hash: "SHA-384", namedCurve: "P-384" };
+        case "ES512":
+            return { name: "ECDSA", hash: "SHA-512", namedCurve: "P-521" };
+        default:
+            return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Validate a DPoP proof JWT per RFC 9449.
+ *
+ * The proof is a compact-serialized JWT whose header contains the public key
+ * (`jwk`) used to sign the proof.  The function:
+ *
+ * 1. Parses the JOSE header and verifies `typ: "dpop+jwt"` and a supported `alg`.
+ * 2. Extracts the embedded `jwk` and imports it via Web Crypto.
+ * 3. Verifies the JWT signature using the imported key.
+ * 4. Validates required claims:
+ *    - `htm` — must match the provided HTTP method.
+ *    - `htu` — must match the provided HTTP URI (scheme + authority + path).
+ *    - `iat` — must be within the acceptable time window.
+ *    - `jti` — must be unique (checked against an in-memory replay cache).
+ * 5. If an `accessToken` is provided, verifies the `ath` (access token hash)
+ *    claim matches the SHA-256 hash of the token.
+ *
+ * Returns the JWK thumbprint on success, or `null` if validation fails.
+ *
+ * @param proof   - The DPoP proof from the `DPoP` request header.
+ * @param method  - The HTTP method of the request (e.g. "POST").
+ * @param url     - The full request URL.
+ * @param accessToken - Optional access token to verify `ath` binding.
+ */
+export async function validateDpopProof(proof, method, url, accessToken) {
+    // ── 1. Split compact serialization ──────────────────────────────
+    const parts = proof.split(".");
+    if (parts.length !== 3)
+        return null;
+    const [headerB64, payloadB64, signatureB64] = parts;
+    // ── 2. Parse header ─────────────────────────────────────────────
+    let header;
+    try {
+        header = JSON.parse(new TextDecoder().decode(base64urlDecode(headerB64)));
+    }
+    catch {
+        return null;
+    }
+    // Must be typ: dpop+jwt
+    if (header.typ !== "dpop+jwt")
+        return null;
+    // Must have a supported algorithm
+    if (!header.alg)
+        return null;
+    const algMapping = mapAlgorithm(header.alg);
+    if (!algMapping)
+        return null;
+    // Must have an embedded JWK
+    if (!header.jwk || typeof header.jwk !== "object")
+        return null;
+    // The JWK must not contain a private key
+    if ("d" in header.jwk)
+        return null;
+    // ── 3. Import the public key and verify signature ───────────────
+    let importAlg;
+    if (algMapping.name === "RSASSA-PKCS1-v1_5") {
+        importAlg = { name: algMapping.name, hash: algMapping.hash };
+    }
+    else {
+        importAlg = {
+            name: algMapping.name,
+            namedCurve: algMapping.namedCurve,
+        };
+    }
+    let publicKey;
+    try {
+        publicKey = await crypto.subtle.importKey("jwk", header.jwk, importAlg, false, ["verify"]);
+    }
+    catch {
+        return null;
+    }
+    // Verify the signature over header.payload
+    const signingInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+    const signature = base64urlDecode(signatureB64);
+    let verifyAlg;
+    if (algMapping.name === "ECDSA") {
+        verifyAlg = { name: "ECDSA", hash: algMapping.hash };
+    }
+    else {
+        verifyAlg = { name: algMapping.name };
+    }
+    let valid;
+    try {
+        valid = await crypto.subtle.verify(verifyAlg, publicKey, signature.buffer, signingInput);
+    }
+    catch {
+        return null;
+    }
+    if (!valid)
+        return null;
+    // ── 4. Parse and validate payload claims ────────────────────────
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder().decode(base64urlDecode(payloadB64)));
+    }
+    catch {
+        return null;
+    }
+    // htm — HTTP method must match
+    if (typeof payload.htm !== "string")
+        return null;
+    if (payload.htm.toUpperCase() !== method.toUpperCase())
+        return null;
+    // htu — HTTP URI must match (scheme + authority + path, no query/fragment)
+    if (typeof payload.htu !== "string")
+        return null;
+    try {
+        const proofUrl = new URL(payload.htu);
+        const requestUrl = new URL(url);
+        // Compare origin + pathname (ignoring query string and fragment).
+        if (proofUrl.origin !== requestUrl.origin ||
+            proofUrl.pathname !== requestUrl.pathname) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    // iat — issued at must be recent
+    if (typeof payload.iat !== "number")
+        return null;
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (payload.iat > nowSeconds + MAX_CLOCK_SKEW_SECONDS)
+        return null;
+    if (nowSeconds - payload.iat > MAX_PROOF_AGE_SECONDS)
+        return null;
+    // jti — unique identifier, prevent replay
+    if (typeof payload.jti !== "string" || payload.jti.length === 0)
+        return null;
+    if (await dpopReplayStore.has(payload.jti))
+        return null;
+    // Record the jti with a TTL matching the proof window.
+    await dpopReplayStore.set(payload.jti, true, JTI_TTL_MS);
+    // ── 5. Access token hash binding (ath) ──────────────────────────
+    if (accessToken !== undefined) {
+        const expectedAth = base64urlEncode(createHash("sha256").update(accessToken).digest());
+        if (payload.ath !== expectedAth)
+            return null;
+    }
+    // ── 6. Compute JWK thumbprint ───────────────────────────────────
+    let thumbprint;
+    try {
+        thumbprint = computeJwkThumbprint(header.jwk);
+    }
+    catch {
+        return null;
+    }
+    return { thumbprint };
+}
+/**
+ * Clear the DPoP JTI replay cache.
+ *
+ * Useful for tests so state does not leak between test cases.
+ */
+export async function clearDpopReplayCache() {
+    await dpopReplayStore.clear();
+}
+//# sourceMappingURL=dpop.js.map

package/dist/dpop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dpop.js","sourceRoot":"","sources":["../src/dpop.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,5 +2,9 @@ export { signSession, verifySession } from "./session.js";
 export { generateApiKey, verifyApiKey, extractApiKeyPrefix, } from "./api-key.js";
 export { createAuthMiddleware } from "./middleware.js";
 export { checkPermission, derivePermission } from "./permissions.js";
+export { validateDpopProof, clearDpopReplayCache, setDpopReplayStore } from "./dpop.js";
+export { extractWorkloadIdentity, isValidSpiffeId } from "./workload.js";
+export type { DpopValidationResult } from "./dpop.js";
+export type { WorkloadIdentity } from "./workload.js";
 export type { AuthConfig, SessionPayload, AgentCredential, AuthContext, AuthResolverDeps, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EACL,cAAc,EACd,YAAY,EACZ,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EACV,UAAU,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EACL,cAAc,EACd,YAAY,EACZ,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACxF,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACzE,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EACV,UAAU,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -2,4 +2,6 @@ export { signSession, verifySession } from "./session.js";
 export { generateApiKey, verifyApiKey, extractApiKeyPrefix, } from "./api-key.js";
 export { createAuthMiddleware } from "./middleware.js";
 export { checkPermission, derivePermission } from "./permissions.js";
+export { validateDpopProof, clearDpopReplayCache, setDpopReplayStore } from "./dpop.js";
+export { extractWorkloadIdentity, isValidSpiffeId } from "./workload.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EACL,cAAc,EACd,YAAY,EACZ,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EACL,cAAc,EACd,YAAY,EACZ,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACxF,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/middleware.d.ts

@@ -4,11 +4,14 @@ import type { AuthConfig, AuthContext, AuthResolverDeps } from "./types.js";
  * incoming `Request`.
  *
  * Resolution order:
- * 1. Session cookie (`capstan_session`) — verifies JWT, returns human context.
- * 2. `Authorization: Bearer <token>` header — if the token matches the
+ * 1. Client certificate / workload identity (`X-Client-Cert` or
+ *    `X-Forwarded-Client-Cert` header) — extracts SPIFFE ID, validates
+ *    trust domain, returns workload context.
+ * 2. Session cookie (`capstan_session`) — verifies JWT, returns human context.
+ * 3. `Authorization: Bearer <token>` header — if the token matches the
  *    configured API key prefix, looks up the agent credential and verifies
  *    the key hash.
- * 3. Falls back to `{ type: "anonymous", isAuthenticated: false }`.
+ * 4. Falls back to `{ type: "anonymous", isAuthenticated: false }`.
  */
 export declare function createAuthMiddleware(config: AuthConfig, deps: AuthResolverDeps): (request: Request) => Promise<AuthContext>;
 //# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,gBAAgB,EACjB,MAAM,YAAY,CAAC;AA2BpB;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,gBAAgB,GACrB,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,WAAW,CAAC,CAuD5C"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,gBAAgB,EACjB,MAAM,YAAY,CAAC;AA6BpB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,gBAAgB,GACrB,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,WAAW,CAAC,CAyG5C"}

package/dist/middleware.js

@@ -1,5 +1,7 @@
 import { verifySession } from "./session.js";
 import { verifyApiKey, extractApiKeyPrefix } from "./api-key.js";
+import { validateDpopProof } from "./dpop.js";
+import { extractWorkloadIdentity } from "./workload.js";
 const SESSION_COOKIE_NAME = "capstan_session";
 const DEFAULT_API_KEY_PREFIX = "cap_ak_";
 const ANONYMOUS_CONTEXT = {
@@ -25,19 +27,41 @@ function parseCookies(header) {
  * incoming `Request`.
  *
  * Resolution order:
- * 1. Session cookie (`capstan_session`) — verifies JWT, returns human context.
- * 2. `Authorization: Bearer <token>` header — if the token matches the
+ * 1. Client certificate / workload identity (`X-Client-Cert` or
+ *    `X-Forwarded-Client-Cert` header) — extracts SPIFFE ID, validates
+ *    trust domain, returns workload context.
+ * 2. Session cookie (`capstan_session`) — verifies JWT, returns human context.
+ * 3. `Authorization: Bearer <token>` header — if the token matches the
  *    configured API key prefix, looks up the agent credential and verifies
  *    the key hash.
- * 3. Falls back to `{ type: "anonymous", isAuthenticated: false }`.
+ * 4. Falls back to `{ type: "anonymous", isAuthenticated: false }`.
  */
 export function createAuthMiddleware(config, deps) {
     const apiKeyPrefix = config.apiKeys?.prefix ?? DEFAULT_API_KEY_PREFIX;
     const authHeaderName = config.apiKeys?.headerName ?? "Authorization";
+    const trustedDomains = config.trustedDomains ?? [];
     return async (request) => {
-        // ── 1. Session cookie ────────────────────────────────────────
+        let authCtx;
+        let accessToken;
+        // ── 1. Workload identity (mTLS / SPIFFE) ─────────────────────
+        if (trustedDomains.length > 0) {
+            const headers = {};
+            for (const [key, value] of request.headers.entries()) {
+                headers[key] = value;
+            }
+            const identity = extractWorkloadIdentity(headers, trustedDomains);
+            if (identity) {
+                authCtx = {
+                    isAuthenticated: true,
+                    type: "workload",
+                    spiffeId: identity.spiffeId,
+                    certFingerprint: identity.certFingerprint,
+                };
+            }
+        }
+        // ── 2. Session cookie ────────────────────────────────────────
         const cookieHeader = request.headers.get("cookie");
-        if (cookieHeader) {
+        if (!authCtx && cookieHeader) {
             const cookies = parseCookies(cookieHeader);
             const sessionToken = cookies.get(SESSION_COOKIE_NAME);
             if (sessionToken) {
@@ -52,35 +76,55 @@ export function createAuthMiddleware(config, deps) {
                         ctx.role = payload.role;
                     if (payload.email !== undefined)
                         ctx.email = payload.email;
-                    return ctx;
+                    authCtx = ctx;
+                    accessToken = sessionToken;
                 }
             }
         }
-        // ── 2. API key via Authorization header ──────────────────────
-        const authHeader = request.headers.get(authHeaderName);
-        if (authHeader) {
-            const token = authHeader.startsWith("Bearer ")
-                ? authHeader.slice(7)
-                : null;
-            if (token && token.startsWith(apiKeyPrefix) && deps.findAgentByKeyPrefix) {
-                const prefix = extractApiKeyPrefix(token);
-                const credential = await deps.findAgentByKeyPrefix(prefix);
-                if (credential && !credential.revokedAt) {
-                    const valid = await verifyApiKey(token, credential.apiKeyHash);
-                    if (valid) {
-                        return {
-                            isAuthenticated: true,
-                            type: "agent",
-                            agentId: credential.id,
-                            agentName: credential.name,
-                            permissions: credential.permissions,
-                        };
+        // ── 3. API key via Authorization header ──────────────────────
+        if (!authCtx) {
+            const authHeader = request.headers.get(authHeaderName);
+            if (authHeader) {
+                const token = authHeader.startsWith("Bearer ")
+                    ? authHeader.slice(7)
+                    : authHeader.startsWith("DPoP ")
+                        ? authHeader.slice(5)
+                        : null;
+                if (token && token.startsWith(apiKeyPrefix) && deps.findAgentByKeyPrefix) {
+                    const prefix = extractApiKeyPrefix(token);
+                    const credential = await deps.findAgentByKeyPrefix(prefix);
+                    if (credential && !credential.revokedAt) {
+                        const valid = await verifyApiKey(token, credential.apiKeyHash);
+                        if (valid) {
+                            authCtx = {
+                                isAuthenticated: true,
+                                type: "agent",
+                                agentId: credential.id,
+                                agentName: credential.name,
+                                permissions: credential.permissions,
+                            };
+                            accessToken = token;
+                        }
                     }
                 }
             }
         }
-        // ── 3. Anonymous ─────────────────────────────────────────────
-        return ANONYMOUS_CONTEXT;
+        // ── 4. DPoP proof validation ─────────────────────────────────
+        // If a DPoP header is present, validate the proof and bind the
+        // token to the key thumbprint.  A missing or invalid proof when
+        // the header is present causes the auth context to be rejected.
+        const dpopHeader = request.headers.get("dpop");
+        if (dpopHeader && authCtx) {
+            const result = await validateDpopProof(dpopHeader, request.method, request.url, accessToken);
+            if (!result) {
+                // DPoP proof failed validation — treat as unauthenticated.
+                return ANONYMOUS_CONTEXT;
+            }
+            // Bind the DPoP thumbprint to the auth context.
+            authCtx.dpopThumbprint = result.thumbprint;
+        }
+        // ── 5. Anonymous ─────────────────────────────────────────────
+        return authCtx ?? ANONYMOUS_CONTEXT;
     };
 }
 //# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pluggable key-value store interface.
+ *
+ * Identical to `@zauso-ai/capstan-core`'s `KeyValueStore` — duplicated here
+ * so that `@zauso-ai/capstan-auth` has no hard dependency on the core package.
+ */
+export interface KeyValueStore<T> {
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+}
+/**
+ * In-memory implementation of `KeyValueStore` with optional per-entry TTL.
+ */
+export declare class MemoryStore<T> implements KeyValueStore<T> {
+    private data;
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,WAAW,CAAC,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IACrD,OAAO,CAAC,IAAI,CAAkE;IAExE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAUxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/store.js

@@ -0,0 +1,33 @@
+/**
+ * In-memory implementation of `KeyValueStore` with optional per-entry TTL.
+ */
+export class MemoryStore {
+    data = new Map();
+    async get(key) {
+        const entry = this.data.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
+            this.data.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    async set(key, value, ttlMs) {
+        this.data.set(key, {
+            value,
+            expiresAt: ttlMs ? Date.now() + ttlMs : undefined,
+        });
+    }
+    async delete(key) {
+        return this.data.delete(key);
+    }
+    async has(key) {
+        const val = await this.get(key); // triggers TTL check
+        return val !== undefined;
+    }
+    async clear() {
+        this.data.clear();
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,OAAO,WAAW;IACd,IAAI,GAAG,IAAI,GAAG,EAAuD,CAAC;IAE9E,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAClE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACtB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAQ,EAAE,KAAc;QAC7C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE;YACjB,KAAK;YACL,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS;SAClD,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,qBAAqB;QACtD,OAAO,GAAG,KAAK,SAAS,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;CACF"}

package/dist/types.d.ts

@@ -7,6 +7,10 @@ export interface AuthConfig {
         prefix?: string;
         headerName?: string;
     };
+    /** Trusted SPIFFE trust domains for mTLS workload authentication. */
+    trustedDomains?: string[];
+    /** Whether to require client certificates (mTLS). */
+    mtls?: boolean;
 }
 export interface SessionPayload {
     userId: string;
@@ -25,13 +29,19 @@ export interface AgentCredential {
 }
 export interface AuthContext {
     isAuthenticated: boolean;
-    type: "human" | "agent" | "anonymous";
+    type: "human" | "agent" | "anonymous" | "workload";
     userId?: string;
     role?: string;
     email?: string;
     agentId?: string;
     agentName?: string;
     permissions?: string[];
+    /** DPoP key thumbprint — present when the request included a valid DPoP proof. */
+    dpopThumbprint?: string;
+    /** SPIFFE ID from client certificate (e.g. "spiffe://example.org/agent/crawler"). */
+    spiffeId?: string;
+    /** Client certificate fingerprint (SHA-256 hex digest). */
+    certFingerprint?: string;
 }
 export interface AuthResolverDeps {
     /** Look up an agent credential by API key prefix */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,CACrB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;CACtC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,CAAC;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,CACrB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;CACtC"}

package/dist/workload.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Parsed workload identity extracted from a client certificate.
+ */
+export interface WorkloadIdentity {
+    /** Full SPIFFE ID URI (e.g. "spiffe://example.org/agent/crawler"). */
+    spiffeId: string;
+    /** Trust domain portion of the SPIFFE ID (e.g. "example.org"). */
+    trustDomain: string;
+    /** Workload path portion of the SPIFFE ID (e.g. "/agent/crawler"). */
+    workloadPath: string;
+    /** SHA-256 hex digest of the PEM-encoded client certificate. */
+    certFingerprint: string;
+}
+/**
+ * Validate that a string is a well-formed SPIFFE ID per the SPIFFE spec:
+ *
+ * - Scheme must be `spiffe`
+ * - Trust domain must be a non-empty hostname-like string (lower-case
+ *   alphanumerics, hyphens, dots; no leading/trailing hyphens or dots).
+ * - Workload path must be non-empty and start with `/`.
+ */
+export declare function isValidSpiffeId(id: string): boolean;
+/**
+ * Extract a workload identity from client certificate information provided
+ * via request headers.
+ *
+ * In a typical deployment the mTLS termination happens at a reverse proxy
+ * (Envoy, Nginx, Istio ingress, etc.) which forwards the client certificate
+ * and its SPIFFE ID through HTTP headers.
+ *
+ * Supported header combinations:
+ *
+ * | SPIFFE ID source                      | Cert source              |
+ * |---------------------------------------|--------------------------|
+ * | `X-Client-Cert-Spiffe-Id` header      | `X-Client-Cert`          |
+ * | `URI=` in `X-Forwarded-Client-Cert`   | `X-Forwarded-Client-Cert`|
+ *
+ * @param certOrHeaders  PEM-encoded client certificate string, or a
+ *                       header map (e.g. from `Object.fromEntries(request.headers)`).
+ * @param trustedDomains Whitelist of SPIFFE trust domains to accept.
+ * @returns The parsed `WorkloadIdentity` if the certificate is present, the
+ *          SPIFFE ID is valid, and the trust domain is in the whitelist.
+ *          Returns `null` otherwise.
+ */
+export declare function extractWorkloadIdentity(certOrHeaders: string | Record<string, string | undefined>, trustedDomains: string[]): WorkloadIdentity | null;
+//# sourceMappingURL=workload.d.ts.map

package/dist/workload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workload.d.ts","sourceRoot":"","sources":["../src/workload.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;CACzB;AAiBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA6BnD;AAkID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC1D,cAAc,EAAE,MAAM,EAAE,GACvB,gBAAgB,GAAG,IAAI,CAyCzB"}

package/dist/workload.js

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+/**
+ * Headers that reverse proxies commonly use to forward client certificates.
+ *
+ * - `x-client-cert` — raw PEM or URL-encoded PEM (Envoy, Nginx, etc.)
+ * - `x-forwarded-client-cert` — Envoy XFCC header (may contain key=value pairs)
+ */
+const CLIENT_CERT_HEADERS = [
+    "x-client-cert",
+    "x-forwarded-client-cert",
+];
+// ---------------------------------------------------------------------------
+// SPIFFE ID validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate that a string is a well-formed SPIFFE ID per the SPIFFE spec:
+ *
+ * - Scheme must be `spiffe`
+ * - Trust domain must be a non-empty hostname-like string (lower-case
+ *   alphanumerics, hyphens, dots; no leading/trailing hyphens or dots).
+ * - Workload path must be non-empty and start with `/`.
+ */
+export function isValidSpiffeId(id) {
+    if (typeof id !== "string" || id.length === 0)
+        return false;
+    // Must start with the spiffe scheme.
+    if (!id.startsWith("spiffe://"))
+        return false;
+    const rest = id.slice("spiffe://".length);
+    // Find the first "/" after the trust domain.
+    const slashIndex = rest.indexOf("/");
+    if (slashIndex <= 0)
+        return false; // no trust domain or no path
+    const trustDomain = rest.slice(0, slashIndex);
+    const workloadPath = rest.slice(slashIndex);
+    // Trust domain: valid DNS-like label(s), no leading/trailing dot or hyphen.
+    if (!isValidTrustDomain(trustDomain))
+        return false;
+    // Workload path must be non-empty (beyond the leading slash).
+    if (workloadPath.length < 2)
+        return false;
+    // Path segments must not be empty (no double slashes) and must not
+    // contain `.` or `..` traversals.
+    const segments = workloadPath.slice(1).split("/");
+    for (const seg of segments) {
+        if (seg.length === 0 || seg === "." || seg === "..")
+            return false;
+    }
+    return true;
+}
+/**
+ * A trust domain is a valid lower-case DNS name: labels separated by dots,
+ * each label consisting of alphanumerics and hyphens, not starting/ending
+ * with a hyphen.
+ */
+function isValidTrustDomain(domain) {
+    if (domain.length === 0 || domain.length > 255)
+        return false;
+    const labels = domain.split(".");
+    for (const label of labels) {
+        if (label.length === 0 || label.length > 63)
+            return false;
+        if (/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(label) === false)
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Certificate parsing helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract the PEM-encoded client certificate from request headers.
+ *
+ * Supports:
+ * - `X-Client-Cert: <PEM or URL-encoded PEM>`
+ * - `X-Forwarded-Client-Cert: Cert="<URL-encoded PEM>"` (Envoy XFCC format)
+ */
+function extractPemFromHeaders(headers) {
+    // Normalise header names to lower case for case-insensitive lookup.
+    const normalised = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (v !== undefined) {
+            normalised[k.toLowerCase()] = v;
+        }
+    }
+    for (const headerName of CLIENT_CERT_HEADERS) {
+        const raw = normalised[headerName];
+        if (!raw || raw.length === 0)
+            continue;
+        // XFCC header from Envoy may look like:
+        //   By=...;Cert="<url-encoded PEM>";Hash=...
+        // Extract the Cert value if present.
+        const certMatch = raw.match(/Cert="([^"]+)"/i);
+        if (certMatch?.[1]) {
+            return decodePem(certMatch[1]);
+        }
+        // Otherwise treat the entire header value as PEM (possibly URL-encoded).
+        return decodePem(raw);
+    }
+    return null;
+}
+/**
+ * Decode a PEM string that may be URL-encoded (common in proxy headers).
+ */
+function decodePem(value) {
+    // If the value contains %2F or %2B it was URL-encoded.
+    if (value.includes("%")) {
+        try {
+            return decodeURIComponent(value);
+        }
+        catch {
+            // Not valid URL encoding — use as-is.
+        }
+    }
+    return value;
+}
+/**
+ * Compute the SHA-256 hex fingerprint of a PEM-encoded certificate.
+ *
+ * The fingerprint is computed over the raw PEM text (including header/footer
+ * lines) to keep the implementation dependency-free.  This is sufficient for
+ * identity-binding purposes as each unique cert will produce a unique hash.
+ */
+function computeCertFingerprint(pem) {
+    return createHash("sha256").update(pem).digest("hex");
+}
+/**
+ * Extract the SPIFFE URI SAN from a PEM-encoded certificate.
+ *
+ * Real X.509 parsing requires ASN.1 decoding which would need a dependency.
+ * Instead we use a pragmatic approach: the SPIFFE ID is looked up from a
+ * companion header (`X-Client-Cert-Spiffe-Id`) that mTLS-terminating proxies
+ * (Envoy, Istio, Linkerd) can be configured to set, or it can be embedded
+ * in the XFCC header as `URI=spiffe://...`.
+ *
+ * If neither is available we fall back to scanning the PEM base64 payload
+ * for the `spiffe://` URI (works for unencrypted certs where the SAN is
+ * visible in the base64 text — a useful heuristic but not a substitute for
+ * real ASN.1 parsing).
+ */
+function extractSpiffeIdFromHeaders(headers) {
+    const normalised = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (v !== undefined) {
+            normalised[k.toLowerCase()] = v;
+        }
+    }
+    // 1. Explicit header set by the proxy.
+    const explicit = normalised["x-client-cert-spiffe-id"];
+    if (explicit && isValidSpiffeId(explicit)) {
+        return explicit;
+    }
+    // 2. XFCC URI field (Envoy sets `URI=spiffe://...`).
+    const xfcc = normalised["x-forwarded-client-cert"];
+    if (xfcc) {
+        const uriMatch = xfcc.match(/URI=(spiffe:\/\/[^;,"]+)/i);
+        if (uriMatch?.[1] && isValidSpiffeId(uriMatch[1])) {
+            return uriMatch[1];
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Extract a workload identity from client certificate information provided
+ * via request headers.
+ *
+ * In a typical deployment the mTLS termination happens at a reverse proxy
+ * (Envoy, Nginx, Istio ingress, etc.) which forwards the client certificate
+ * and its SPIFFE ID through HTTP headers.
+ *
+ * Supported header combinations:
+ *
+ * | SPIFFE ID source                      | Cert source              |
+ * |---------------------------------------|--------------------------|
+ * | `X-Client-Cert-Spiffe-Id` header      | `X-Client-Cert`          |
+ * | `URI=` in `X-Forwarded-Client-Cert`   | `X-Forwarded-Client-Cert`|
+ *
+ * @param certOrHeaders  PEM-encoded client certificate string, or a
+ *                       header map (e.g. from `Object.fromEntries(request.headers)`).
+ * @param trustedDomains Whitelist of SPIFFE trust domains to accept.
+ * @returns The parsed `WorkloadIdentity` if the certificate is present, the
+ *          SPIFFE ID is valid, and the trust domain is in the whitelist.
+ *          Returns `null` otherwise.
+ */
+export function extractWorkloadIdentity(certOrHeaders, trustedDomains) {
+    if (trustedDomains.length === 0)
+        return null;
+    let pem;
+    let spiffeId;
+    if (typeof certOrHeaders === "string") {
+        // Raw PEM string provided directly — cannot extract SPIFFE ID from
+        // headers, so this path is only useful if the caller also provides
+        // the SPIFFE ID separately.  For header-based flows use the object form.
+        pem = certOrHeaders.length > 0 ? certOrHeaders : null;
+        spiffeId = null;
+    }
+    else {
+        pem = extractPemFromHeaders(certOrHeaders);
+        spiffeId = extractSpiffeIdFromHeaders(certOrHeaders);
+    }
+    // We need both a certificate (for fingerprinting) and a SPIFFE ID.
+    if (!pem || !spiffeId)
+        return null;
+    if (!isValidSpiffeId(spiffeId))
+        return null;
+    // Parse the trust domain from the SPIFFE ID.
+    const rest = spiffeId.slice("spiffe://".length);
+    const slashIndex = rest.indexOf("/");
+    if (slashIndex <= 0)
+        return null;
+    const trustDomain = rest.slice(0, slashIndex);
+    const workloadPath = rest.slice(slashIndex);
+    // Verify the trust domain is in the whitelist.
+    if (!trustedDomains.includes(trustDomain))
+        return null;
+    const certFingerprint = computeCertFingerprint(pem);
+    return {
+        spiffeId,
+        trustDomain,
+        workloadPath,
+        certFingerprint,
+    };
+}
+//# sourceMappingURL=workload.js.map

package/dist/workload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workload.js","sourceRoot":"","sources":["../src/workload.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zauso-ai/capstan-auth",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.6",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,7 +12,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
   },
   "description": "Authentication for Capstan — JWT sessions, API key auth for AI agents, permissions",
   "files": [