@zauso-ai/capstan-auth 0.2.0 → 0.3.1

package/dist/types.d.ts

@@ -1,40 +1,148 @@
+export type AuthContextType = "human" | "agent" | "anonymous" | "workload";
+export type ActorKind = "user" | "agent" | "workload" | "system" | "anonymous";
+export type CredentialKind = "session" | "oauth" | "api_key" | "mtls" | "dpop" | "run_token" | "approval_token" | "anonymous";
+export type ExecutionKind = "request" | "run" | "tool_call" | "approval" | "schedule" | "release" | "mcp_invocation";
+export interface AuthCookieConfig {
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+export interface AuthGrant {
+    resource: string;
+    action: string;
+    scope?: Record<string, string>;
+    effect?: "allow" | "deny";
+    expiresAt?: string;
+    constraints?: Record<string, unknown>;
+}
+export interface AuthGrantRequirement {
+    resource: string;
+    action: string;
+    scope?: Record<string, string>;
+}
+export interface ActorIdentity {
+    kind: ActorKind;
+    id: string;
+    displayName?: string;
+    role?: string;
+    email?: string;
+    claims?: Record<string, unknown>;
+}
+export interface CredentialProof {
+    kind: CredentialKind;
+    subjectId: string;
+    presentedAt: string;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionIdentity {
+    kind: ExecutionKind;
+    id: string;
+    parentId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface DelegationTargetRef {
+    kind: ActorKind | ExecutionKind;
+    id: string;
+}
+export interface DelegationLink {
+    from: DelegationTargetRef;
+    to: DelegationTargetRef;
+    reason: string;
+    issuedAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AuthEnvelope {
+    actor: ActorIdentity;
+    credential: CredentialProof;
+    execution?: ExecutionIdentity;
+    delegation: DelegationLink[];
+    grants: AuthGrant[];
+}
 export interface AuthConfig {
     session: {
         secret: string;
         maxAge?: string;
+        issuer?: string;
+        audience?: string;
+        cookieName?: string;
+        cookie?: AuthCookieConfig;
     };
     apiKeys?: {
         prefix?: string;
         headerName?: string;
     };
+    /** Trusted SPIFFE trust domains for mTLS workload authentication. */
+    trustedDomains?: string[];
+    /** Whether to require client certificates (mTLS). */
+    mtls?: boolean;
+    /** OAuth 2.0 provider configuration for Google, GitHub, etc. */
+    oauth?: import("./oauth.js").OAuthConfig;
 }
 export interface SessionPayload {
     userId: string;
     email?: string;
     role?: string;
+    displayName?: string;
+    permissions?: string[];
+    claims?: Record<string, unknown>;
+    sessionId?: string;
+    iss?: string;
+    aud?: string | string[];
     iat: number;
     exp: number;
 }
+export interface SessionSigningOptions {
+    maxAge?: string;
+    issuer?: string;
+    audience?: string | string[];
+}
+export interface SessionVerificationOptions {
+    issuer?: string;
+    audience?: string;
+}
 export interface AgentCredential {
     id: string;
     name: string;
     apiKeyHash: string;
     apiKeyPrefix: string;
     permissions: string[];
+    grants?: AuthGrant[];
+    claims?: Record<string, unknown>;
     revokedAt?: string;
 }
 export interface AuthContext {
     isAuthenticated: boolean;
-    type: "human" | "agent" | "anonymous";
+    type: AuthContextType;
+    actor: ActorIdentity;
+    credential: CredentialProof;
+    execution?: ExecutionIdentity;
+    delegation: DelegationLink[];
+    grants: AuthGrant[];
+    envelope?: AuthEnvelope;
     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 */
     findAgentByKeyPrefix?: (prefix: string) => Promise<AgentCredential | null>;
+    /** Resolve extra grants after credential verification. */
+    resolveAdditionalGrants?: (auth: AuthContext, request: Request) => Promise<AuthGrant[] | string[] | undefined>;
+    /** Attach richer execution identity to the resolved auth envelope. */
+    resolveExecution?: (auth: AuthContext, request: Request) => Promise<ExecutionIdentity | undefined>;
+    /** Attach delegation provenance for runtime / harness flows. */
+    resolveDelegation?: (auth: AuthContext, request: Request) => Promise<DelegationLink[] | undefined>;
 }
 //# sourceMappingURL=types.d.ts.map

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":"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"}

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": "0.2.0",
+  "version": "0.3.1",
   "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": [