@keycardai/express 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @keycardai/express
+
+> **Preview.** This SDK has not reached parity with the Keycard Python SDK. APIs may change between minor versions.
+
+Keycard auth middleware for Express. Wraps Express's standard middleware idioms for protecting HTTP APIs with Keycard: bearer token validation (RFC 6750), delegated token exchange (RFC 8693), and OAuth discovery routes (RFC 9728 + RFC 8414).
+
+## Installation
+
+```bash
+npm install @keycardai/express express
+```
+
+## Quick Start
+
+### Protect routes with `requireBearerAuth`
+
+```typescript
+import express from "express";
+import { requireBearerAuth } from "@keycardai/express";
+
+const app = express();
+
+app.use(requireBearerAuth({ issuer: "https://your-zone.keycard.cloud" }));
+
+app.get("/api/data", (req, res) => {
+  // req.auth is AccessToken: { token, clientId, scopes, ... }
+  res.json({ clientId: req.auth.clientId });
+});
+```
+
+### Delegate tokens with `grant`
+
+```typescript
+import { requireBearerAuth, grant } from "@keycardai/express";
+import { ClientSecret } from "@keycardai/oauth/server";
+
+const credential = new ClientSecret("your-client-id", "your-client-secret");
+
+app.use(requireBearerAuth({ issuer: "https://your-zone.keycard.cloud" }));
+app.use(grant(["https://graph.microsoft.com"], {
+  zoneUrl: "https://your-zone.keycard.cloud",
+  applicationCredential: credential,
+}));
+
+app.get("/api/email", async (req, res) => {
+  const token = req.accessContext.access("https://graph.microsoft.com");
+  // use token.accessToken to call Graph API
+  res.json({ ok: true });
+});
+```
+
+### Add OAuth discovery routes
+
+```typescript
+import { keycardMetadataRouter } from "@keycardai/express";
+
+app.use(keycardMetadataRouter({ issuer: "https://your-zone.keycard.cloud" }));
+// Serves:
+//   GET /.well-known/oauth-protected-resource  (RFC 9728)
+//   GET /.well-known/oauth-authorization-server (RFC 8414, proxied)
+```
+
+## API
+
+| Export | Description |
+|---|---|
+| `requireBearerAuth(options)` | Middleware factory that validates a Bearer token and sets `req.auth: AccessToken`. Returns 401 with RFC 6750 `WWW-Authenticate` challenge on failure. |
+| `grant(resources, options)` | Middleware factory that exchanges the bearer token for per-resource access tokens and sets `req.accessContext: AccessContext`. Must run after `requireBearerAuth`. |
+| `keycardMetadataRouter(options)` | Returns an Express Router with `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server` routes. |
+| `AuthenticatedRequest` | `Request` extended with `auth: AccessToken`. |
+| `GrantedRequest` | `Request` extended with `auth: AccessToken` and `accessContext: AccessContext`. |
+
+## Related Packages
+
+- [`@keycardai/oauth`](../oauth/) — Framework-free OAuth primitives this package builds on
+- [`@keycardai/mcp`](../mcp/) — MCP-specific OAuth integration
+- [Keycard TypeScript SDK](../../README.md) — Root documentation

package/dist/cjs/bearerAuth.d.ts

@@ -0,0 +1,76 @@
+import type { Request, RequestHandler } from "express";
+import { TokenVerifier } from "@keycardai/oauth/server/tokenVerifier";
+import type { TokenVerifierOptions } from "@keycardai/oauth/server/tokenVerifier";
+import type { AccessToken } from "@keycardai/oauth/server/accessToken";
+/**
+ * Extends Express `Request` with the verified Keycard `AccessToken`.
+ *
+ * Cast inside handlers that run after `requireBearerAuth()`:
+ * ```ts
+ * app.get("/data", (req, res) => {
+ *   const { auth } = req as AuthenticatedRequest;
+ * });
+ * ```
+ *
+ * Alternatively, adopt Express module augmentation so `req.auth` is
+ * available without casting across your entire app:
+ * ```ts
+ * import type { AccessToken } from "@keycardai/oauth/server";
+ * declare global {
+ *   namespace Express {
+ *     interface Request {
+ *       auth?: AccessToken;
+ *     }
+ *   }
+ * }
+ * ```
+ * We ship the interface-extension form rather than augmenting the global
+ * namespace by default. Augmentation makes `req.auth` optional on every
+ * request including unauthenticated routes, which weakens the type
+ * contract. Use it when you prefer convenience over strictness.
+ * See: https://github.com/auth0/express-jwt/issues/311
+ */
+export interface AuthenticatedRequest extends Request {
+    auth: AccessToken;
+}
+export type BearerAuthOptions = {
+    verifier: TokenVerifier;
+    requiredScopes?: readonly string[];
+} | {
+    /**
+     * Keycard zone URL, e.g. "https://zone-id.keycard.cloud".
+     * Either `zoneUrl` or `zoneId` is required (consistent with `grant()`).
+     */
+    zoneUrl?: string;
+    /**
+     * Keycard zone ID. Constructs the URL as `https://{zoneId}.keycard.cloud`.
+     * Either `zoneUrl` or `zoneId` is required (consistent with `grant()`).
+     */
+    zoneId?: string;
+    audience?: string;
+    enableMultiZone?: boolean;
+    keyring?: TokenVerifierOptions["keyring"];
+    requiredScopes?: readonly string[];
+};
+/**
+ * Express middleware that validates a Bearer token (RFC 6750) and sets
+ * `req.auth` to the verified `AccessToken`.
+ *
+ * On failure: responds with a `WWW-Authenticate` challenge containing the
+ * `resource_metadata` URL per RFC 9728 §3.
+ *
+ * Usage with a zone URL:
+ * ```ts
+ * app.use(requireBearerAuth({ zoneUrl: "https://zone.keycard.cloud" }));
+ * // or by zone ID
+ * app.use(requireBearerAuth({ zoneId: "zone-id" }));
+ * ```
+ *
+ * Usage with a pre-built verifier (shared across routes):
+ * ```ts
+ * const verifier = new TokenVerifier({ issuer: "https://zone.keycard.cloud" });
+ * app.use(requireBearerAuth({ verifier }));
+ * ```
+ */
+export declare function requireBearerAuth(options: BearerAuthOptions): RequestHandler;
+//# sourceMappingURL=bearerAuth.d.ts.map

package/dist/cjs/bearerAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearerAuth.d.ts","sourceRoot":"","sources":["../../src/bearerAuth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AASvE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,oBAAqB,SAAQ,OAAO;IACnD,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC/D;IACE;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC1C,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,CAAC;AAEN;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAgG5E"}

package/dist/cjs/bearerAuth.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireBearerAuth = requireBearerAuth;
+const tokenVerifier_1 = require("@keycardai/oauth/server/tokenVerifier");
+const errors_1 = require("@keycardai/oauth/errors");
+/**
+ * Express middleware that validates a Bearer token (RFC 6750) and sets
+ * `req.auth` to the verified `AccessToken`.
+ *
+ * On failure: responds with a `WWW-Authenticate` challenge containing the
+ * `resource_metadata` URL per RFC 9728 §3.
+ *
+ * Usage with a zone URL:
+ * ```ts
+ * app.use(requireBearerAuth({ zoneUrl: "https://zone.keycard.cloud" }));
+ * // or by zone ID
+ * app.use(requireBearerAuth({ zoneId: "zone-id" }));
+ * ```
+ *
+ * Usage with a pre-built verifier (shared across routes):
+ * ```ts
+ * const verifier = new TokenVerifier({ issuer: "https://zone.keycard.cloud" });
+ * app.use(requireBearerAuth({ verifier }));
+ * ```
+ */
+function requireBearerAuth(options) {
+    // Do not pass requiredScopes to TokenVerifier: it returns null on scope
+    // failure, which the middleware would interpret as a generic 401. The
+    // explicit scope check below produces the correct 403 InsufficientScopeError.
+    let verifier;
+    if ("verifier" in options) {
+        verifier = options.verifier;
+    }
+    else {
+        const issuer = options.zoneUrl ?? buildIssuerFromZoneId(options.zoneId);
+        if (!issuer) {
+            throw new Error("requireBearerAuth: either `zoneUrl` or `zoneId` is required");
+        }
+        verifier = new tokenVerifier_1.TokenVerifier({
+            issuer,
+            audience: options.audience,
+            enableMultiZone: options.enableMultiZone,
+            keyring: options.keyring,
+        });
+    }
+    return async (req, res, next) => {
+        const resourceMetadataUrl = getResourceMetadataUrl(req);
+        try {
+            const authorization = req.headers.authorization;
+            if (!authorization) {
+                throw new errors_1.UnauthorizedError("No credentials");
+            }
+            const [scheme, token] = authorization.split(" ");
+            if (!token) {
+                throw new errors_1.BadRequestError("Malformed credentials");
+            }
+            if (scheme.toLowerCase() !== "bearer") {
+                throw new errors_1.InvalidTokenError("Unsupported authentication scheme");
+            }
+            const accessToken = await verifier.verifyToken(token);
+            if (!accessToken) {
+                throw new errors_1.InvalidTokenError("Token validation failed");
+            }
+            // Validate resource audience: a token scoped to a different resource
+            // server must not be accepted here. Compare origins so path and query
+            // string differences are ignored (mirrors Workers auth.ts:88-92).
+            if (accessToken.resource) {
+                const requestOrigin = `${req.protocol}://${req.host}`;
+                try {
+                    const tokenOrigin = new URL(accessToken.resource).origin;
+                    if (tokenOrigin !== requestOrigin) {
+                        throw new errors_1.InvalidTokenError("Token not intended for resource");
+                    }
+                }
+                catch (e) {
+                    if (e instanceof errors_1.InvalidTokenError)
+                        throw e;
+                    // resource claim is not a URL; opaque audience, skip origin check
+                }
+            }
+            if ("requiredScopes" in options &&
+                options.requiredScopes &&
+                options.requiredScopes.length > 0) {
+                const hasAllScopes = options.requiredScopes.every((scope) => accessToken.scopes.includes(scope));
+                if (!hasAllScopes) {
+                    throw new errors_1.InsufficientScopeError("Insufficient scope");
+                }
+            }
+            req.auth = accessToken;
+            next();
+        }
+        catch (error) {
+            if (error instanceof errors_1.BadRequestError) {
+                res.status(400).end();
+            }
+            else if (error instanceof errors_1.UnauthorizedError) {
+                res.set("WWW-Authenticate", `Bearer resource_metadata="${resourceMetadataUrl}"`);
+                res.status(401).end();
+            }
+            else if (error instanceof errors_1.InsufficientScopeError) {
+                res.set("WWW-Authenticate", `Bearer error="${error.errorCode}", error_description="${error.message}", resource_metadata="${resourceMetadataUrl}"`);
+                res.status(403).end();
+            }
+            else if (error instanceof errors_1.OAuthError || error instanceof errors_1.InvalidTokenError) {
+                res.set("WWW-Authenticate", `Bearer error="${error.errorCode}", error_description="${error.message}", resource_metadata="${resourceMetadataUrl}"`);
+                res.status(401).end();
+            }
+            else {
+                next(error);
+            }
+        }
+    };
+}
+function getResourceMetadataUrl(req) {
+    const origin = `${req.protocol}://${req.host}`;
+    return `${origin}/.well-known/oauth-protected-resource`;
+}
+function buildIssuerFromZoneId(zoneId) {
+    if (!zoneId)
+        return undefined;
+    return `https://${zoneId}.keycard.cloud`;
+}
+//# sourceMappingURL=bearerAuth.js.map

package/dist/cjs/bearerAuth.js.map

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

package/dist/cjs/grant.d.ts

@@ -0,0 +1,46 @@
+import type { RequestHandler } from "express";
+import { AccessContext } from "@keycardai/oauth/server/accessContext";
+import type { ApplicationCredential } from "@keycardai/oauth/credentials";
+import type { AuthenticatedRequest } from "./bearerAuth.js";
+export interface GrantedRequest extends AuthenticatedRequest {
+    accessContext: AccessContext;
+}
+export interface GrantOptions {
+    /**
+     * Keycard zone URL, e.g. "https://zone-id.keycard.cloud".
+     * Either `zoneUrl` or `zoneId` is required.
+     */
+    zoneUrl?: string;
+    /**
+     * Keycard zone ID. Constructs the zone URL as
+     * `https://{zoneId}.keycard.cloud`.
+     */
+    zoneId?: string;
+    /**
+     * Application credential provider for authenticated token exchange.
+     * When omitted, the bearer token is exchanged without client auth.
+     */
+    applicationCredential?: ApplicationCredential;
+}
+/**
+ * Express middleware factory for delegated token exchange (RFC 8693).
+ *
+ * Must run AFTER `requireBearerAuth()`. Reads the verified bearer token
+ * from `req.auth`, exchanges it for per-resource access tokens at the
+ * Keycard zone, and stores the results in `req.accessContext`.
+ *
+ * On success, `req.accessContext.access(resourceUrl)` returns the
+ * `TokenResponse` for that resource. On partial failure, some resources
+ * may have errors while others succeed.
+ *
+ * ```ts
+ * app.use(requireBearerAuth({ issuer: "https://zone.keycard.cloud" }));
+ * app.use(grant(["https://graph.microsoft.com"], { zoneUrl: "https://zone.keycard.cloud" }));
+ * app.get("/data", (req, res) => {
+ *   const token = req.accessContext.access("https://graph.microsoft.com");
+ *   // ...
+ * });
+ * ```
+ */
+export declare function grant(resources: string | readonly string[], options: GrantOptions): RequestHandler;
+//# sourceMappingURL=grant.d.ts.map

package/dist/cjs/grant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant.d.ts","sourceRoot":"","sources":["../../src/grant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/E,OAAO,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AACtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG5D,MAAM,WAAW,cAAe,SAAQ,oBAAoB;IAC1D,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,KAAK,CACnB,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACrC,OAAO,EAAE,YAAY,GACpB,cAAc,CA2EhB"}

package/dist/cjs/grant.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.grant = grant;
+const tokenExchange_1 = require("@keycardai/oauth/tokenExchange");
+const accessContext_1 = require("@keycardai/oauth/server/accessContext");
+const errors_1 = require("@keycardai/oauth/errors");
+/**
+ * Express middleware factory for delegated token exchange (RFC 8693).
+ *
+ * Must run AFTER `requireBearerAuth()`. Reads the verified bearer token
+ * from `req.auth`, exchanges it for per-resource access tokens at the
+ * Keycard zone, and stores the results in `req.accessContext`.
+ *
+ * On success, `req.accessContext.access(resourceUrl)` returns the
+ * `TokenResponse` for that resource. On partial failure, some resources
+ * may have errors while others succeed.
+ *
+ * ```ts
+ * app.use(requireBearerAuth({ issuer: "https://zone.keycard.cloud" }));
+ * app.use(grant(["https://graph.microsoft.com"], { zoneUrl: "https://zone.keycard.cloud" }));
+ * app.get("/data", (req, res) => {
+ *   const token = req.accessContext.access("https://graph.microsoft.com");
+ *   // ...
+ * });
+ * ```
+ */
+function grant(resources, options) {
+    const zoneUrl = options.zoneUrl ?? buildZoneUrl(options.zoneId);
+    if (!zoneUrl) {
+        throw new errors_1.AuthProviderConfigurationError("grant: either `zoneUrl` or `zoneId` is required");
+    }
+    return async (req, _res, next) => {
+        const authReq = req;
+        const subjectToken = authReq.auth?.token;
+        const accessCtx = new accessContext_1.AccessContext();
+        if (!subjectToken) {
+            accessCtx.setError({
+                message: "No authentication token. Ensure requireBearerAuth() runs before grant().",
+            });
+            req.accessContext = accessCtx;
+            return next();
+        }
+        let client;
+        try {
+            const auth = options.applicationCredential?.getAuth();
+            client = new tokenExchange_1.TokenExchangeClient(zoneUrl, auth ?? undefined);
+        }
+        catch (e) {
+            accessCtx.setError({
+                message: "Failed to initialize token exchange client.",
+                rawError: String(e),
+            });
+            req.accessContext = accessCtx;
+            return next();
+        }
+        const resourceList = Array.isArray(resources)
+            ? resources
+            : [resources];
+        const tokens = {};
+        for (const resource of resourceList) {
+            try {
+                let exchangeRequest;
+                if (options.applicationCredential) {
+                    exchangeRequest = await options.applicationCredential.prepareTokenExchangeRequest(subjectToken, resource);
+                }
+                else {
+                    exchangeRequest = {
+                        subjectToken,
+                        resource,
+                        subjectTokenType: "urn:ietf:params:oauth:token-type:access_token",
+                    };
+                }
+                tokens[resource] = await client.exchangeToken(exchangeRequest);
+            }
+            catch (e) {
+                const detail = {
+                    message: `Token exchange failed for ${resource}`,
+                };
+                if (e instanceof errors_1.OAuthError) {
+                    detail.code = e.errorCode;
+                    detail.description = e.message;
+                }
+                else {
+                    detail.rawError = String(e);
+                }
+                accessCtx.setResourceError(resource, detail);
+            }
+        }
+        accessCtx.setBulkTokens(tokens);
+        req.accessContext = accessCtx;
+        next();
+    };
+}
+function buildZoneUrl(zoneId) {
+    if (!zoneId)
+        return undefined;
+    return `https://${zoneId}.keycard.cloud`;
+}
+//# sourceMappingURL=grant.js.map

package/dist/cjs/grant.js.map

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

package/dist/cjs/index.d.ts

@@ -0,0 +1,9 @@
+export { requireBearerAuth } from "./bearerAuth.js";
+export type { AuthenticatedRequest, BearerAuthOptions } from "./bearerAuth.js";
+export { grant } from "./grant.js";
+export type { GrantedRequest, GrantOptions } from "./grant.js";
+export { keycardMetadataRouter } from "./wellKnown.js";
+export type { KeycardRouterOptions } from "./wellKnown.js";
+export { createKeycardMiddleware } from "./middleware.js";
+export type { KeycardMiddlewareOptions, KeycardMiddleware } from "./middleware.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,YAAY,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKeycardMiddleware = exports.keycardMetadataRouter = exports.grant = exports.requireBearerAuth = void 0;
+var bearerAuth_js_1 = require("./bearerAuth.js");
+Object.defineProperty(exports, "requireBearerAuth", { enumerable: true, get: function () { return bearerAuth_js_1.requireBearerAuth; } });
+var grant_js_1 = require("./grant.js");
+Object.defineProperty(exports, "grant", { enumerable: true, get: function () { return grant_js_1.grant; } });
+var wellKnown_js_1 = require("./wellKnown.js");
+Object.defineProperty(exports, "keycardMetadataRouter", { enumerable: true, get: function () { return wellKnown_js_1.keycardMetadataRouter; } });
+var middleware_js_1 = require("./middleware.js");
+Object.defineProperty(exports, "createKeycardMiddleware", { enumerable: true, get: function () { return middleware_js_1.createKeycardMiddleware; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,iDAAoD;AAA3C,kHAAA,iBAAiB,OAAA;AAE1B,uCAAmC;AAA1B,iGAAA,KAAK,OAAA;AAEd,+CAAuD;AAA9C,qHAAA,qBAAqB,OAAA;AAE9B,iDAA0D;AAAjD,wHAAA,uBAAuB,OAAA"}

package/dist/cjs/middleware.d.ts

@@ -0,0 +1,54 @@
+import type { RequestHandler } from "express";
+import type { ApplicationCredential } from "@keycardai/oauth/credentials";
+export interface KeycardMiddlewareOptions {
+    /**
+     * Keycard zone URL, e.g. "https://zone-id.keycard.cloud".
+     * Either `zoneUrl` or `zoneId` is required.
+     */
+    zoneUrl?: string;
+    /**
+     * Keycard zone ID. Constructs the URL as `https://{zoneId}.keycard.cloud`.
+     */
+    zoneId?: string;
+    /**
+     * Application credential for token exchange in `grant()`.
+     * Typically a `ClientSecret` from `@keycardai/oauth/server`.
+     */
+    applicationCredential?: ApplicationCredential;
+}
+export interface KeycardMiddleware {
+    /**
+     * Express middleware that validates a Bearer token and sets `req.auth`.
+     * Accepts optional `requiredScopes` to enforce at the middleware level.
+     */
+    requireBearerAuth(options?: {
+        requiredScopes?: readonly string[];
+    }): RequestHandler;
+    /**
+     * Express middleware for delegated RFC 8693 token exchange.
+     * Sets `req.accessContext` with per-resource tokens.
+     */
+    grant(resources: string | readonly string[], options?: {
+        applicationCredential?: ApplicationCredential;
+    }): RequestHandler;
+}
+/**
+ * Creates a pair of pre-configured Keycard middleware functions sharing a
+ * common zone URL. Eliminates the naming mismatch between `requireBearerAuth`
+ * (which takes `issuer`) and `grant` (which takes `zoneUrl`/`zoneId`) by
+ * accepting a single consistent config.
+ *
+ * Python equivalent: `AuthProvider(zone_url=..., application_credential=...)`
+ *
+ * ```ts
+ * const keycard = createKeycardMiddleware({
+ *   zoneUrl: "https://zone.keycard.cloud",
+ *   applicationCredential: new ClientSecret("client-id", "client-secret"),
+ * });
+ *
+ * app.use(keycard.requireBearerAuth());
+ * app.use(keycard.grant(["https://graph.microsoft.com"]));
+ * ```
+ */
+export declare function createKeycardMiddleware(options: KeycardMiddlewareOptions): KeycardMiddleware;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/cjs/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE1E,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,iBAAiB,CAAC,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,cAAc,CAAC;IACpF;;;OAGG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACrC,OAAO,CAAC,EAAE;QACR,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;KAC/C,GACA,cAAc,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAsB5F"}

package/dist/cjs/middleware.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKeycardMiddleware = createKeycardMiddleware;
+const bearerAuth_js_1 = require("./bearerAuth.js");
+const grant_js_1 = require("./grant.js");
+/**
+ * Creates a pair of pre-configured Keycard middleware functions sharing a
+ * common zone URL. Eliminates the naming mismatch between `requireBearerAuth`
+ * (which takes `issuer`) and `grant` (which takes `zoneUrl`/`zoneId`) by
+ * accepting a single consistent config.
+ *
+ * Python equivalent: `AuthProvider(zone_url=..., application_credential=...)`
+ *
+ * ```ts
+ * const keycard = createKeycardMiddleware({
+ *   zoneUrl: "https://zone.keycard.cloud",
+ *   applicationCredential: new ClientSecret("client-id", "client-secret"),
+ * });
+ *
+ * app.use(keycard.requireBearerAuth());
+ * app.use(keycard.grant(["https://graph.microsoft.com"]));
+ * ```
+ */
+function createKeycardMiddleware(options) {
+    const zoneUrl = options.zoneUrl ?? buildZoneUrl(options.zoneId);
+    if (!zoneUrl) {
+        throw new Error("createKeycardMiddleware: either `zoneUrl` or `zoneId` is required");
+    }
+    return {
+        requireBearerAuth(localOptions) {
+            return (0, bearerAuth_js_1.requireBearerAuth)({
+                zoneUrl,
+                requiredScopes: localOptions?.requiredScopes,
+            });
+        },
+        grant(resources, localOptions) {
+            return (0, grant_js_1.grant)(resources, {
+                zoneUrl,
+                applicationCredential: localOptions?.applicationCredential ?? options.applicationCredential,
+            });
+        },
+    };
+}
+function buildZoneUrl(zoneId) {
+    if (!zoneId)
+        return undefined;
+    return `https://${zoneId}.keycard.cloud`;
+}
+//# sourceMappingURL=middleware.js.map

package/dist/cjs/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":";;AA0DA,0DAsBC;AA/ED,mDAAoD;AACpD,yCAAmC;AAsCnC;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,uBAAuB,CAAC,OAAiC;IACvE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IAED,OAAO;QACL,iBAAiB,CAAC,YAAqD;YACrE,OAAO,IAAA,iCAAiB,EAAC;gBACvB,OAAO;gBACP,cAAc,EAAE,YAAY,EAAE,cAAc;aAC7C,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,SAAS,EAAE,YAAY;YAC3B,OAAO,IAAA,gBAAK,EAAC,SAAS,EAAE;gBACtB,OAAO;gBACP,qBAAqB,EACnB,YAAY,EAAE,qBAAqB,IAAI,OAAO,CAAC,qBAAqB;aACvE,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,MAAe;IACnC,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,OAAO,WAAW,MAAM,gBAAgB,CAAC;AAC3C,CAAC"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}

package/dist/cjs/wellKnown.d.ts

@@ -0,0 +1,48 @@
+import { Router } from "express";
+export interface KeycardRouterOptions {
+    /**
+     * Keycard issuer URL, e.g. "https://zone-id.keycard.cloud".
+     * Used to proxy AS metadata from the Keycard authorization server.
+     */
+    issuer: string;
+    /**
+     * Human-readable resource name shown in AS metadata.
+     */
+    resourceName?: string;
+    /**
+     * Scopes this resource server supports.
+     */
+    scopesSupported?: readonly string[];
+    /**
+     * Link to documentation for this resource.
+     */
+    resourceDocumentation?: string;
+    /**
+     * Timeout in milliseconds for the upstream AS metadata fetch.
+     * Default: 10 000 ms.
+     */
+    asMetadataTimeoutMs?: number;
+}
+/**
+ * Returns an Express Router that serves the two OAuth discovery endpoints
+ * required by RFC 9728 and RFC 8414:
+ *
+ * - `GET /.well-known/oauth-protected-resource` (RFC 9728 §2)
+ * - `GET /.well-known/oauth-authorization-server` (RFC 8414 §3, proxied)
+ *
+ * Mount it at the application root:
+ * ```ts
+ * import express from "express";
+ * import { keycardMetadataRouter } from "@keycardai/express";
+ *
+ * const app = express();
+ * app.use(keycardMetadataRouter({ issuer: "https://zone.keycard.cloud" }));
+ * ```
+ *
+ * These paths must remain publicly accessible (no bearer auth) per their
+ * respective specs. Per the security guidance in
+ * `@keycardai/starlette` and the feedback_specific_path_bypass rule:
+ * only bypass auth for these exact paths, never a broad `/.well-known/` prefix.
+ */
+export declare function keycardMetadataRouter(options: KeycardRouterOptions): Router;
+//# sourceMappingURL=wellKnown.d.ts.map

package/dist/cjs/wellKnown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wellKnown.d.ts","sourceRoot":"","sources":["../../src/wellKnown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGjC,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;OAEG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAc3E"}