@north-light/crouter-identity 0.3.360 → 0.3.362

package/dist/index.d.ts

@@ -20,9 +20,11 @@ export declare class JwksCache {
     private readonly fetcher;
     private keys;
     private lastUnknownRefresh;
+    private loading;
     private discovery;
     constructor(issuer: string, fetcher?: typeof fetch, jwksUri?: string);
     load(): Promise<JSONWebKeySet>;
+    private fetchKeys;
     forKid(kid: string | undefined): Promise<JSONWebKeySet>;
 }
 export declare function verifyAccessToken(options: {
@@ -31,6 +33,44 @@ export declare function verifyAccessToken(options: {
     issuer: string;
     audience: string;
 }): Promise<AccessTokenClaims>;
+/** One level of the outbound token's RFC 8693 `act` nesting: the actor, and the actor it acted for. */
+export interface OutboundActor {
+    sub: string;
+    act?: OutboundActor;
+}
+/** The claims of the outbound token the directory mints for one provider call (contract 3). */
+export interface OutboundTokenClaims extends JWTPayload {
+    iss: string;
+    aud: string;
+    /** The user the call is made for, `user:<id>`. */
+    sub: string;
+    /** The principal the grant was issued to, `app:<id>` or the user. */
+    grantee: string;
+    /** The runtime's registered OAuth client id. */
+    client_id: string;
+    /** The provider's `<provider>:<group>` strings the caller holds, space-separated; may be empty. */
+    scope: string;
+    initiating_app: string;
+    /** Audit only; nothing authorizes on it. */
+    act: OutboundActor;
+    iat: number;
+    exp: number;
+    jti: string;
+}
+/**
+ * Verifies the outbound token a provider receives (contract 3 D3-TOK-12): ES256 or RS256 with
+ * a `kid`, typ `at+jwt`, signature against `jwks` (a `JwksCache` refetches once on an unknown
+ * `kid`), `iss` = `issuer`, `aud` exactly `audience` (a trailing-slash difference is refused),
+ * and `exp`. `sub` must be a `user:` principal and `grantee` and `initiating_app`
+ * an `app:` or `user:` principal; the remaining claims are checked for presence and type only; which of them gates a
+ * call is the caller's rule (D3-TOK-13 gates on `scope` alone, and nothing gates on `act`).
+ */
+export declare function verifyOutboundToken(options: {
+    token: string;
+    jwks: JSONWebKeySet | JwksCache;
+    issuer: string;
+    audience: string;
+}): Promise<OutboundTokenClaims>;
 export interface SyncNoticeClaims extends JWTPayload {
     purpose: 'grant_sync';
     iat: number;

package/dist/index.js

@@ -73,6 +73,7 @@ export class JwksCache {
     fetcher;
     keys;
     lastUnknownRefresh = -Infinity;
+    loading;
     discovery;
     constructor(issuer, fetcher = fetch, jwksUri) {
         this.issuer = issuer;
@@ -81,6 +82,18 @@ export class JwksCache {
             this.discovery = { jwks_uri: jwksUri };
     }
     async load() {
+        if (this.loading)
+            return this.loading;
+        const loading = this.fetchKeys();
+        this.loading = loading;
+        try {
+            return await loading;
+        }
+        finally {
+            this.loading = undefined;
+        }
+    }
+    async fetchKeys() {
         if (!this.discovery) {
             const response = await this.fetcher(`${this.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`);
             if (!response.ok)
@@ -104,6 +117,10 @@ export class JwksCache {
             return this.load();
         if (this.keys.keys.some((key) => key.kid === kid))
             return this.keys;
+        // Concurrent requests for a newly published kid must await the same refetch, not use
+        // the stale set while the 30-second unknown-kid throttle is running.
+        if (this.loading)
+            return this.loading;
         if (Date.now() - this.lastUnknownRefresh >= 30_000) {
             this.lastUnknownRefresh = Date.now();
             await this.load();
@@ -132,6 +149,41 @@ export async function verifyAccessToken(options) {
     }
     return payload;
 }
+function nonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
+function appOrUser(value) {
+    return validatePrincipal(value, 'app') || validatePrincipal(value, 'user');
+}
+function isActor(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && nonEmptyString(value.sub);
+}
+/**
+ * Verifies the outbound token a provider receives (contract 3 D3-TOK-12): ES256 or RS256 with
+ * a `kid`, typ `at+jwt`, signature against `jwks` (a `JwksCache` refetches once on an unknown
+ * `kid`), `iss` = `issuer`, `aud` exactly `audience` (a trailing-slash difference is refused),
+ * and `exp`. `sub` must be a `user:` principal and `grantee` and `initiating_app`
+ * an `app:` or `user:` principal; the remaining claims are checked for presence and type only; which of them gates a
+ * call is the caller's rule (D3-TOK-13 gates on `scope` alone, and nothing gates on `act`).
+ */
+export async function verifyOutboundToken(options) {
+    const header = decodeProtectedHeader(options.token);
+    if (header.typ !== 'at+jwt' || (header.alg !== 'ES256' && header.alg !== 'RS256'))
+        throw new Error('Invalid outbound token header');
+    if (!nonEmptyString(header.kid))
+        throw new Error('Outbound token has no key id');
+    const keys = await keySet(options.jwks, header.kid);
+    const { payload } = await jwtVerify(options.token, createLocalJWKSet(keys), {
+        issuer: options.issuer, audience: options.audience, algorithms: ['ES256', 'RS256'], typ: 'at+jwt', requiredClaims: ['exp'],
+    });
+    if (payload.aud !== options.audience || typeof payload.exp !== 'number' || typeof payload.iat !== 'number' ||
+        !validatePrincipal(payload.sub, 'user') || !appOrUser(payload.grantee) || !nonEmptyString(payload.client_id) ||
+        typeof payload.scope !== 'string' || !appOrUser(payload.initiating_app) || !isActor(payload.act) ||
+        !nonEmptyString(payload.jti)) {
+        throw new Error('Invalid outbound token claims');
+    }
+    return payload;
+}
 /** The directory's grant-sync notice: ES256 with the directory signing key named
  *  by `kid`, no `typ`, `aud` = the runtime's registered URL, a lifetime of at most
  *  five minutes, and a `jti` the runtime uses to answer replays without a sync. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-identity",
-  "version": "0.3.360",
+  "version": "0.3.362",
   "description": "Northlight access-token verification and scope rules",
   "type": "module",
   "main": "./dist/index.js",