@absolutejs/auth 0.56.12 → 0.56.14

package/dist/oidc/keys.d.ts

@@ -1,4 +1,4 @@
-type SigningKeyIdentity = {
+export type SigningKeyIdentity = {
     kid: string;
     publicJwk: JsonWebKey;
 };
@@ -12,10 +12,10 @@ export type SigningKey = SigningKeyIdentity & ({
     privateJwk?: never;
     sign: (input: Uint8Array) => Promise<Uint8Array>;
 });
-export declare const generateSigningKey: () => Promise<SigningKey>;
-export declare const jwkThumbprint: (jwk: JsonWebKey) => Promise<string>;
-export declare const signJwt: (payload: Record<string, unknown>, signing: SigningKey, typ?: string) => Promise<string>;
-export declare const toPublicJwk: (key: SigningKey) => {
+declare const generateSigningKey: () => Promise<SigningKey>;
+declare const jwkThumbprint: (jwk: JsonWebKey) => Promise<string>;
+declare const signJwt: (payload: Record<string, unknown>, signing: SigningKey, typ?: string) => Promise<string>;
+declare const toPublicJwk: (key: SigningKeyIdentity) => {
     alg: string;
     crv: string | undefined;
     kid: string;
@@ -24,7 +24,7 @@ export declare const toPublicJwk: (key: SigningKey) => {
     x: string | undefined;
     y: string | undefined;
 };
-export declare const verifyJwt: (token: string, publicJwk: JsonWebKey) => Promise<{
+declare const verifyJwt: (token: string, publicJwk: JsonWebKey) => Promise<{
     header: {
         [k: string]: any;
     };
@@ -32,4 +32,19 @@ export declare const verifyJwt: (token: string, publicJwk: JsonWebKey) => Promis
         [k: string]: any;
     };
 } | undefined>;
-export {};
+/** Resolves the active signing identity followed by still-valid previous
+ * public identities. Duplicate key IDs fail closed because a JWT `kid` must
+ * identify exactly one verification key during an overlap window. */
+declare const signingVerificationKeys: (active: SigningKeyIdentity, previous?: readonly SigningKeyIdentity[]) => SigningKeyIdentity[];
+/** Verifies an Absolute Auth JWT against the exact public identity named by
+ * its protected `kid` header. This keeps already-issued tokens valid while a
+ * previous public key remains in the configured overlap window. */
+declare const verifyJwtWithKeys: (token: string, keys: readonly SigningKeyIdentity[]) => Promise<{
+    header: {
+        [k: string]: any;
+    };
+    payload: {
+        [k: string]: any;
+    };
+} | undefined>;
+export { generateSigningKey, jwkThumbprint, signingVerificationKeys, signJwt, toPublicJwk, verifyJwt, verifyJwtWithKeys };

package/dist/server.js

@@ -3206,6 +3206,95 @@ var agentAuthContextPlugin = (config) => new Elysia2({
   }
 })).as("global");
 
+// src/agents/oauthGuide.ts
+var DEFAULT_GUIDE_ROUTE = "/auth.md";
+var secureUrl = (value, label) => {
+  const url = new URL(value);
+  const loopback = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+  if (url.protocol !== "https:" && !loopback)
+    throw new Error(`${label} must use HTTPS outside loopback development`);
+  if (url.username || url.password || url.hash)
+    throw new Error(`${label} cannot contain credentials or a fragment`);
+  return url.toString();
+};
+var agentOAuthGuideRoute = (config) => config.route ?? DEFAULT_GUIDE_ROUTE;
+var agentOAuthGuideUrl = (config) => new URL(agentOAuthGuideRoute(config), secureUrl(config.authorizationServer, "OAuth authorization server")).toString();
+var normalizedResources = (config) => {
+  if (config.resources.length === 0)
+    throw new Error("Agent OAuth guide requires at least one resource");
+  const resources = config.resources.map((resource) => ({
+    metadataUrl: secureUrl(resource.metadataUrl, "Protected-resource metadata URL"),
+    name: resource.name.trim(),
+    resource: secureUrl(resource.resource, "OAuth protected resource"),
+    scopes: [
+      ...new Set(resource.scopes.map((scope) => scope.trim()))
+    ].filter(Boolean)
+  }));
+  if (resources.some(({ name, scopes }) => !name || scopes.length === 0))
+    throw new Error("Every agent OAuth guide resource requires a name and at least one scope");
+  if (new Set(resources.map(({ resource }) => resource)).size !== resources.length)
+    throw new Error("Agent OAuth guide resources must be unique");
+  return resources;
+};
+var resourceSections = (resources) => resources.map((resource) => `### ${resource.name}
+
+- Protected resource: \`${resource.resource}\`
+- Metadata: ${resource.metadataUrl}
+- Allowed scopes: ${resource.scopes.map((scope) => `\`${scope}\``).join(", ")}
+`).join(`
+`);
+var generateAgentOAuthGuide = (config) => {
+  if (!config.serviceName.trim())
+    throw new Error("Agent OAuth guide requires a service name");
+  const authorizationServer = secureUrl(config.authorizationServer, "OAuth authorization server");
+  const resources = normalizedResources(config);
+  const authorizationMetadata = new URL("/.well-known/oauth-authorization-server", authorizationServer).toString();
+  return `# OAuth access for ${config.serviceName.trim()}
+
+This guide is the agent-readable companion to the service's standards-based
+OAuth metadata. Discovery metadata is authoritative. Do not infer endpoints,
+scopes, audiences, or capabilities that are not advertised.
+
+## 1. Discover
+
+Fetch the protected-resource metadata for the exact interface you intend to
+use, then fetch the authorization-server metadata at
+${authorizationMetadata}.
+
+${resourceSections(resources)}
+## 2. Register the OAuth client
+
+Use an existing registered client or the advertised \`registration_endpoint\`.
+Request only scopes listed for the selected protected resource. Never register
+redirect URIs, grant types, or authentication methods the metadata rejects.
+
+## 3. Obtain user delegation
+
+For an interactive user, use authorization code with PKCE. For a device or
+headless client, use the device authorization grant only when
+\`device_authorization_endpoint\` is advertised. Send the selected protected
+resource as the OAuth \`resource\` value and show the exact requested scopes to
+the user before consent.
+
+## 4. Call the selected interface
+
+Present the access token in the Authorization header. The token must name the
+selected resource as its audience and contain the required scope. A token for
+one resource or transport is not authority for another.
+
+## Safety
+
+- Never ask a user to send a password, passkey response, MFA code, device code,
+  authorization code, client secret, refresh token, or access token to the
+  agent or place one in model context.
+- Stop on issuer, signature, audience, expiry, delegation, or scope failure.
+- Treat consent denial, revocation, and disabled interfaces as final until the
+  user explicitly starts a new authorization flow.
+- Discovery is not authorization, and this guide grants no capability by
+  itself.
+`;
+};
+
 // src/agents/registration.ts
 init_constants();
 init_crypto();
@@ -3289,6 +3378,26 @@ var verifyJwt = async (token, publicJwk) => {
     payload
   };
 };
+var signingVerificationKeys = (active, previous = []) => {
+  const keys = [active, ...previous];
+  const keyIds = new Set(keys.map(({ kid }) => kid));
+  if (keyIds.size !== keys.length)
+    throw new Error("OIDC signing key IDs must be unique");
+  return keys;
+};
+var verifyJwtWithKeys = async (token, keys) => {
+  const [headerSegment] = token.split(".");
+  if (!headerSegment)
+    return;
+  const header = decodeSegment(headerSegment);
+  const kid = header?.kid;
+  if (typeof kid !== "string" || kid.length === 0)
+    return;
+  const key = keys.find((candidate) => candidate.kid === kid);
+  if (!key)
+    return;
+  return verifyJwt(token, key.publicJwk);
+};
 
 // src/agents/registration.ts
 var AGENT_CLAIM_GRANT_TYPE = "urn:workos:agent-auth:grant-type:claim";
@@ -3297,7 +3406,7 @@ var AGENT_IDENTITY_ASSERTION_TYPE = "urn:ietf:params:oauth:token-type:id-jag";
 var DEFAULT_IDENTITY_ROUTE = "/agent/identity";
 var DEFAULT_CLAIM_ROUTE = "/agent/identity/claim";
 var DEFAULT_COMPLETE_ROUTE = "/agent/identity/claim/complete";
-var DEFAULT_GUIDE_ROUTE = "/auth.md";
+var DEFAULT_GUIDE_ROUTE2 = "/auth.md";
 var DEFAULT_CLAIM_TTL_MS = 24 * 60 * MILLISECONDS_IN_A_MINUTE;
 var DEFAULT_ATTEMPT_TTL_MS = 10 * MILLISECONDS_IN_A_MINUTE;
 var DEFAULT_ASSERTION_TTL_MS = 60 * MILLISECONDS_IN_A_MINUTE;
@@ -3332,7 +3441,7 @@ var agentRegistrationEndpoints = (config) => {
   return {
     claimEndpoint: new URL(registration.claimRoute ?? DEFAULT_CLAIM_ROUTE, base).toString(),
     completeEndpoint: new URL(registration.completeRoute ?? DEFAULT_COMPLETE_ROUTE, base).toString(),
-    guide: new URL(registration.guideRoute ?? DEFAULT_GUIDE_ROUTE, base).toString(),
+    guide: new URL(registration.guideRoute ?? DEFAULT_GUIDE_ROUTE2, base).toString(),
     identityEndpoint: new URL(registration.identityRoute ?? DEFAULT_IDENTITY_ROUTE, base).toString(),
     tokenEndpoint: new URL(`${oidcRoute}/token`, base).toString()
   };
@@ -3960,7 +4069,18 @@ var agentAuthRoutes = (config) => {
   if (config === undefined)
     return plugin.as("global");
   if (config.agentRegistration === undefined) {
-    return plugin.get(config.metadataRoute ?? DEFAULT_AGENT_RESOURCE_METADATA_ROUTE, () => agentProtectedResourceMetadata(config)).as("global");
+    plugin.get(config.metadataRoute ?? DEFAULT_AGENT_RESOURCE_METADATA_ROUTE, () => agentProtectedResourceMetadata(config));
+    const { oauthGuide } = config;
+    if (oauthGuide === undefined)
+      return plugin.as("global");
+    const guide = generateAgentOAuthGuide(oauthGuide);
+    plugin.get(agentOAuthGuideRoute(oauthGuide), () => new Response(guide, {
+      headers: {
+        "cache-control": "public, max-age=300",
+        "content-type": "text/markdown; charset=utf-8"
+      }
+    }));
+    return plugin.as("global");
   }
   const registration = config.agentRegistration;
   const identityRoute = registration.identityRoute ?? "/agent/identity";
@@ -6086,7 +6206,7 @@ var exchangeToken = async ({
   requestedScopes,
   subjectToken
 }) => {
-  const verified = await verifyJwt(subjectToken, config.signingKey.publicJwk);
+  const verified = await verifyJwtWithKeys(subjectToken, signingVerificationKeys(config.signingKey, config.previousSigningKeys));
   const payload = verified?.payload;
   if (payload === undefined || typeof payload.sub !== "string" || typeof payload.exp !== "number" || payload.exp <= nowSeconds(now)) {
     return { error: "invalid_grant", ok: false };
@@ -6207,7 +6327,7 @@ var introspectToken = async ({
   token
 }) => {
   if (hint !== "refresh_token") {
-    const verified = await verifyJwt(token, config.signingKey.publicJwk);
+    const verified = await verifyJwtWithKeys(token, signingVerificationKeys(config.signingKey, config.previousSigningKeys));
     const payload = verified?.payload;
     if (payload !== undefined && typeof payload.sub === "string" && typeof payload.exp === "number" && payload.exp > nowSeconds(now)) {
       return {
@@ -7123,7 +7243,7 @@ var verifyIdTokenHint = async ({
   config,
   idTokenHint
 }) => {
-  const verified = await verifyJwt(idTokenHint, config.signingKey.publicJwk);
+  const verified = await verifyJwtWithKeys(idTokenHint, signingVerificationKeys(config.signingKey, config.previousSigningKeys));
   const payload = verified?.payload;
   if (payload === undefined || typeof payload.sub !== "string" || typeof payload.aud !== "string" || payload.iss !== config.issuer) {
     return;
@@ -7353,7 +7473,7 @@ var fetchUserInfo = async ({
       ok: false
     };
   }
-  const verified = await verifyJwt(token, config.signingKey.publicJwk);
+  const verified = await verifyJwtWithKeys(token, signingVerificationKeys(config.signingKey, config.previousSigningKeys));
   if (verified === undefined) {
     return {
       body: { error: "invalid_token" },
@@ -8694,7 +8814,9 @@ var oidcProviderRoutes = (config) => {
     headers: t15.Object({
       authorization: t15.Optional(t15.String())
     })
-  }).get(jwksRoute, () => ({ keys: [toPublicJwk(signingKey)] })).get("/.well-known/openid-configuration", () => discovery).get("/.well-known/oauth-authorization-server", () => discovery);
+  }).get(jwksRoute, () => ({
+    keys: signingVerificationKeys(signingKey, config.previousSigningKeys).map(toPublicJwk)
+  })).get("/.well-known/openid-configuration", () => discovery).get("/.well-known/oauth-authorization-server", () => discovery);
 };
 
 // src/organizations/routes.ts
@@ -26741,7 +26863,7 @@ var createPostgresScimTokenStore = (db) => ({
 });
 // src/agents/registrationClient.ts
 var isObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-var secureUrl = (value, allowLocalhost) => {
+var secureUrl2 = (value, allowLocalhost) => {
   if (typeof value !== "string")
     return;
   try {
@@ -26831,32 +26953,32 @@ var discoverAgentRegistration = async (resource, options = {}) => {
   const request = options.request ?? fetch;
   const maxBytes = options.maxResponseBytes ?? 256 * 1024;
   const allowLocalhost = options.allowInsecureLocalhost === true;
-  const resourceUrl = secureUrl(resource, allowLocalhost);
+  const resourceUrl = secureUrl2(resource, allowLocalhost);
   if (resourceUrl === undefined)
     throw new Error("Resource URL must use HTTPS");
   const resourceMetadataUrl = new URL("/.well-known/oauth-protected-resource", resourceUrl).toString();
   const prm = await requestJson(request, resourceMetadataUrl, {}, maxBytes);
-  const advertisedResource = secureUrl(prm.body.resource, allowLocalhost);
+  const advertisedResource = secureUrl2(prm.body.resource, allowLocalhost);
   if (advertisedResource === undefined || advertisedResource !== resourceUrl) {
     throw new Error("Protected resource metadata identity mismatch");
   }
-  const authorizationServer = secureUrl(stringArray(prm.body.authorization_servers)[0], allowLocalhost);
+  const authorizationServer = secureUrl2(stringArray(prm.body.authorization_servers)[0], allowLocalhost);
   if (authorizationServer === undefined) {
     throw new Error("No secure authorization server is advertised");
   }
   const asUrl = new URL("/.well-known/oauth-authorization-server", authorizationServer).toString();
   const metadata = await requestJson(request, asUrl, {}, maxBytes);
-  if (secureUrl(metadata.body.issuer, allowLocalhost) !== authorizationServer) {
+  if (secureUrl2(metadata.body.issuer, allowLocalhost) !== authorizationServer) {
     throw new Error("Authorization server issuer mismatch");
   }
-  const tokenEndpoint = secureUrl(metadata.body.token_endpoint, allowLocalhost);
+  const tokenEndpoint = secureUrl2(metadata.body.token_endpoint, allowLocalhost);
   const agentAuth = metadata.body.agent_auth;
   if (tokenEndpoint === undefined || !isObject2(agentAuth)) {
     throw new Error("Authorization server does not advertise agent registration");
   }
-  const identityEndpoint = secureUrl(agentAuth.identity_endpoint, allowLocalhost);
-  const claimEndpoint = secureUrl(agentAuth.claim_endpoint, allowLocalhost);
-  const skill = secureUrl(agentAuth.skill, allowLocalhost);
+  const identityEndpoint = secureUrl2(agentAuth.identity_endpoint, allowLocalhost);
+  const claimEndpoint = secureUrl2(agentAuth.claim_endpoint, allowLocalhost);
+  const skill = secureUrl2(agentAuth.skill, allowLocalhost);
   const assertionMetadata = agentAuth.identity_assertion;
   if (identityEndpoint === undefined || claimEndpoint === undefined || skill === undefined || !isObject2(assertionMetadata)) {
     throw new Error("Agent registration metadata is incomplete");
@@ -27033,6 +27155,7 @@ var createOidcAgentCredentialVerifier = ({
   isUsedDpopJti,
   maxDpopAgeMs,
   publicJwk,
+  publicKeys,
   requireDpop = false,
   resource
 }) => {
@@ -27044,13 +27167,14 @@ var createOidcAgentCredentialVerifier = ({
     const token = authorization.slice(authorization.indexOf(" ") + 1).trim();
     if (token.length === 0)
       return;
-    const verified = await verifyJwt(token, publicJwk);
+    const verified = publicKeys ? await verifyJwtWithKeys(token, publicKeys) : await verifyJwt(token, publicJwk);
     const payload = verified?.payload;
     if (payload === undefined || payload.iss !== issuer || typeof payload.exp !== "number" || payload.exp <= Math.floor(Date.now() / MS_PER_SECOND7) || !readAudience(payload.aud).includes(resource) || typeof payload.client_id !== "string") {
       return;
     }
     const confirmation = payload.cnf;
-    const boundJkt = typeof confirmation === "object" && confirmation !== null && typeof confirmation.jkt === "string" ? confirmation.jkt : undefined;
+    const boundJktValue = typeof confirmation === "object" && confirmation !== null ? Reflect.get(confirmation, "jkt") : undefined;
+    const boundJkt = typeof boundJktValue === "string" ? boundJktValue : undefined;
     if (boundJkt !== undefined || requireDpop) {
       if (!authorization.startsWith("DPoP "))
         return;
@@ -27614,7 +27738,7 @@ var createPostgresApiKeyStore = (db) => ({
   }
 });
 // src/oidc/clientIdMetadata.ts
-var secureUrl2 = (value) => {
+var secureUrl3 = (value) => {
   try {
     return new URL(value).protocol === "https:";
   } catch {
@@ -27625,7 +27749,7 @@ var validateClientIdMetadataDocument = (document, expectedClientId) => {
   const errors = [];
   if (document.client_id !== expectedClientId)
     errors.push("client_id does not match the metadata document URL");
-  if (!secureUrl2(document.client_id))
+  if (!secureUrl3(document.client_id))
     errors.push("client_id must use HTTPS");
   if (!Array.isArray(document.redirect_uris) || document.redirect_uris.length === 0)
     errors.push("redirect_uris is required");
@@ -27645,7 +27769,7 @@ var validateClientIdMetadataDocument = (document, expectedClientId) => {
     ["tos_uri", document.tos_uri],
     ["jwks_uri", document.jwks_uri]
   ]) {
-    if (value !== undefined && !secureUrl2(value))
+    if (value !== undefined && !secureUrl3(value))
       errors.push(`${name2} must use HTTPS`);
   }
   return errors;
@@ -27668,7 +27792,7 @@ var createClientIdMetadataResolver = ({
 }) => {
   const cache = new Map;
   return async (clientId) => {
-    if (!secureUrl2(clientId) || !await allow(clientId))
+    if (!secureUrl3(clientId) || !await allow(clientId))
       return;
     const cached = cache.get(clientId);
     if (cached !== undefined && cached.expiresAt > now())
@@ -30347,6 +30471,22 @@ var buildAuthApplications = async (configuration) => {
       tokenTtlMs: registration2.tokenTtlMs
     });
   }
+  if (agentAuth?.oauthGuide !== undefined) {
+    if (oidc === undefined)
+      throw new Error("agentAuth.oauthGuide requires the OIDC provider");
+    if (agentAuth.authorizationServer !== oidc.issuer)
+      throw new Error("agentAuth.authorizationServer must equal oidc.issuer");
+    if (agentAuth.oauthGuide.authorizationServer !== agentAuth.authorizationServer)
+      throw new Error("agentAuth.oauthGuide.authorizationServer must equal agentAuth.authorizationServer");
+    const unknownGuideScopes = agentAuth.oauthGuide.resources.flatMap(({ scopes }) => scopes).filter((scope) => !agentAuth.scopes.includes(scope));
+    if (unknownGuideScopes.length > 0)
+      throw new Error(`Agent OAuth guide uses undeclared scopes: ${[
+        ...new Set(unknownGuideScopes)
+      ].join(", ")}`);
+    if (agentAuth.agentRegistration !== undefined && (agentAuth.agentRegistration.guideRoute ?? "/auth.md") === (agentAuth.oauthGuide.route ?? "/auth.md"))
+      throw new Error("Agent OAuth and registration guides cannot use the same route");
+    generateAgentOAuthGuide(agentAuth.oauthGuide);
+  }
   if (tracing !== undefined)
     await initTracing(tracing);
   const clientProviders = await buildClientProviders(providersConfiguration, createOAuth2Client, customProviders);
@@ -30368,6 +30508,9 @@ var buildAuthApplications = async (configuration) => {
     ...oidc,
     additionalDiscoveryMetadata: {
       ...oidc.additionalDiscoveryMetadata,
+      ...resolvedAgentAuth?.oauthGuide === undefined ? {} : {
+        service_documentation: agentOAuthGuideUrl(resolvedAgentAuth.oauthGuide)
+      },
       ...resolvedAgentAuth?.agentRegistration === undefined ? {} : {
         agent_auth: agentRegistrationDiscoveryMetadata(resolvedAgentAuth)
       }
@@ -30587,5 +30730,5 @@ export {
   auth2 as auth
 };
 
-//# debugId=DC157A619FC3907564756E2164756E21
+//# debugId=E2F70FC52266FF6C64756E2164756E21
 //# sourceMappingURL=server.js.map