@t4h.framework/jwks 0.6.0 → 0.7.1

package/.ai/skills/framework-jwks/SKILL.md

@@ -27,7 +27,7 @@ Package path: `framework/packages/jwks`. See [README.md](../../../README.md) for
 |-------|---------|
 | `@t4h.framework/jwks` | `JWKSAuthorization`, `JWKSAuthorizationContext`, `JWKSAuthorizationManifest`, `JWKSAlgorithm`, re-exports authorize module |
 | `@t4h.framework/jwks/authorize` | Default async handler: `(context) => Promise<boolean>` |
-| `@t4h.framework/jwks/callback` | Default export `jwksCallback`: `(auth, request) => Promise<boolean>`, the `jwt` authorizer hosts pass to the core `AsyncActivityCallback.authorize` |
+| `@t4h.framework/jwks/callback` | Default export `jwksCallback`: `(auth, delivery) => Promise<boolean>`, the authorizer hosts pass to the core `AsyncActivityCallback.authorize` for `jwt` (bearer JWT) and `jwks` (detached signature over the body, key resolved by `kid` from a JWKS URL) |
 
 ```typescript
 import {

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @t4h.framework/jwks
 
+## 0.7.1
+
+### Patch Changes
+
+- Updated dependencies [[`9449e4e`](https://github.com/tech4humans-brasil/framework/commit/9449e4e9889f42dea1d52418140f47d25dff0535), [`9449e4e`](https://github.com/tech4humans-brasil/framework/commit/9449e4e9889f42dea1d52418140f47d25dff0535)]:
+  - @t4h.framework/core@0.15.0
+
+## 0.7.0
+
+### Minor Changes
+
+- [#170](https://github.com/tech4humans-brasil/framework/pull/170) [`aa72268`](https://github.com/tech4humans-brasil/framework/commit/aa72268d040a743743cac31cc14e26b8620b0e3f) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Adds the `jwks` callback auth: a detached signature over the callback body,
+  verified with the public key the `kid` resolves to at a JWKS URL — the way Amber
+  signs its webhooks.
+
+  **core**: `AsyncActivityCallbackAuthJwks` joins `AsyncActivityCallbackAuth`
+  (`jwksUri`, `header`, `kid`/`kidHeader`, `algorithm`/`algorithmHeader`,
+  `signatureFormat`/`signatureFormatHeader`, `timestampHeader`,
+  `toleranceInSeconds`, `signedPayload` as a template over `{timestamp}` and
+  `{body}`).
+
+  **jwks**: `jwksCallback` (default of `@t4h.framework/jwks/callback`) now serves
+  both `jwt` and `jwks`. Hosts pass it as `{ jwt: jwksCallback, jwks: jwksCallback }`.
+
+  **dev**: loads `@t4h.framework/jwks` for the `jwks` type as well.
+
+  **webhook**: documents the new type.
+
+### Patch Changes
+
+- Updated dependencies [[`aa72268`](https://github.com/tech4humans-brasil/framework/commit/aa72268d040a743743cac31cc14e26b8620b0e3f)]:
+  - @t4h.framework/core@0.14.0
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -12,7 +12,7 @@ Requires `@t4h.framework/core` (same major line as this package).
 |------------------|---------|
 | `@t4h.framework/jwks` | `JWKSAuthorization`, `JWKSAuthorizationContext`, and related types |
 | `@t4h.framework/jwks/authorize` | Default async handler invoked by the runtime with the manifest context |
-| `@t4h.framework/jwks/callback` | Default export `jwksCallback`: `jwt` callback authorizer for the core `AsyncActivityCallback.authorize` (`pending({ auth: { type: 'jwt' } })`) |
+| `@t4h.framework/jwks/callback` | Default export `jwksCallback`: the `jwt` (bearer JWT) and `jwks` (detached signature verified with a JWKS key) callback authorizer for the core `AsyncActivityCallback.authorize` |
 
 ## `JWKSAuthorization`
 

package/dist/jwks-callback.d.ts

@@ -1,3 +1,3 @@
-import { AsyncActivityCallback, type AsyncActivityCallbackAuthJwt } from '@t4h.framework/core';
-export default function jwksCallback(auth: AsyncActivityCallbackAuthJwt, request: AsyncActivityCallback.Delivery): Promise<boolean>;
+import { AsyncActivityCallback, type AsyncActivityCallbackAuthJwks, type AsyncActivityCallbackAuthJwt } from '@t4h.framework/core';
+export default function jwksCallback(auth: AsyncActivityCallbackAuthJwt | AsyncActivityCallbackAuthJwks, delivery: AsyncActivityCallback.Delivery): Promise<boolean>;
 //# sourceMappingURL=jwks-callback.d.ts.map

package/dist/jwks-callback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwks-callback.d.ts","sourceRoot":"","sources":["../src/jwks-callback.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,EAClC,MAAM,qBAAqB,CAAA;AAI5B,wBAA8B,YAAY,CACxC,IAAI,EAAE,4BAA4B,EAClC,OAAO,EAAE,qBAAqB,CAAC,QAAQ,GACtC,OAAO,CAAC,OAAO,CAAC,CAmBlB"}
+{"version":3,"file":"jwks-callback.d.ts","sourceRoot":"","sources":["../src/jwks-callback.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EAClC,MAAM,qBAAqB,CAAA;AAyG5B,wBAA8B,YAAY,CACxC,IAAI,EAAE,4BAA4B,GAAG,6BAA6B,EAClE,QAAQ,EAAE,qBAAqB,CAAC,QAAQ,GACvC,OAAO,CAAC,OAAO,CAAC,CAIlB"}

package/dist/jwks-callback.js

@@ -1,7 +1,27 @@
 import { AsyncActivityCallback, } from '@t4h.framework/core';
 import jwks from './jwks-authorize.js';
-export default async function jwksCallback(auth, request) {
-    const token = AsyncActivityCallback.getBearerToken(request.headers, auth.header);
+function isWithinTolerance(timestamp, toleranceInSeconds) {
+    const value = timestamp.trim();
+    if (!value)
+        return false;
+    const signedAt = /^\d+$/.test(value)
+        ? value.length >= 13
+            ? Number(value)
+            : Number(value) * 1000
+        : Date.parse(value);
+    if (Number.isNaN(signedAt))
+        return false;
+    return Math.abs(Date.now() - signedAt) / 1000 <= toleranceInSeconds;
+}
+function fromHeaderOrValue(headers, value, header) {
+    if (value !== undefined)
+        return value;
+    if (!header)
+        return undefined;
+    return AsyncActivityCallback.getHeader(headers, header);
+}
+async function verifyJwt(auth, delivery) {
+    const token = AsyncActivityCallback.getBearerToken(delivery.headers, auth.header);
     if (!token)
         return false;
     try {
@@ -17,4 +37,39 @@ export default async function jwksCallback(auth, request) {
         return false;
     }
 }
+async function verifyDetachedSignature(auth, delivery) {
+    const { headers } = delivery;
+    const signature = AsyncActivityCallback.getHeader(headers, auth.header);
+    if (!signature)
+        return false;
+    const timestamp = auth.timestampHeader
+        ? AsyncActivityCallback.getHeader(headers, auth.timestampHeader)
+        : undefined;
+    if (auth.timestampHeader && !timestamp)
+        return false;
+    if (auth.toleranceInSeconds !== undefined &&
+        !isWithinTolerance(timestamp ?? '', auth.toleranceInSeconds))
+        return false;
+    const rawPayload = (auth.signedPayload ?? '{body}')
+        .replaceAll('{timestamp}', timestamp ?? '')
+        .replaceAll('{body}', delivery.rawBody);
+    try {
+        return await jwks({
+            url: auth.jwksUri,
+            signature,
+            rawPayload,
+            kid: fromHeaderOrValue(headers, auth.kid, auth.kidHeader),
+            algorithm: fromHeaderOrValue(headers, auth.algorithm, auth.algorithmHeader),
+            signatureFormat: fromHeaderOrValue(headers, auth.signatureFormat, auth.signatureFormatHeader) ?? 'hex',
+        });
+    }
+    catch {
+        return false;
+    }
+}
+export default async function jwksCallback(auth, delivery) {
+    if (auth.type === 'jwks')
+        return verifyDetachedSignature(auth, delivery);
+    return verifyJwt(auth, delivery);
+}
 //# sourceMappingURL=jwks-callback.js.map

package/dist/jwks-callback.js.map

@@ -1 +1 @@
-{"version":3,"file":"jwks-callback.js","sourceRoot":"","sources":["../src/jwks-callback.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAEtB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,IAAI,MAAM,qBAAqB,CAAA;AAEtC,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,YAAY,CACxC,IAAkC,EAClC,OAAuC;IAEvC,MAAM,KAAK,GAAG,qBAAqB,CAAC,cAAc,CAChD,OAAO,CAAC,OAAO,EACf,IAAI,CAAC,MAAM,CACZ,CAAA;IAED,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAA;IAExB,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC;YAChB,GAAG,EAAE,IAAI,CAAC,OAAO;YACjB,SAAS,EAAE,KAAK;YAChB,UAAU,EAAE,EAAE;YACd,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC,CAAA;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"jwks-callback.js","sourceRoot":"","sources":["../src/jwks-callback.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/jwks",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "JWKS module for the T4H Framework authorization",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/jwks",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -41,13 +41,13 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.13.0",
+    "@t4h.framework/core": "^0.15.0",
     "@types/jsonwebtoken": "^9",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.13.0"
+    "@t4h.framework/core": "^0.15.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {