@t4h.framework/jwks 0.5.2 → 0.7.0

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

@@ -27,6 +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, 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 {
@@ -132,8 +133,8 @@ Behavior (from `jwks-authorize.ts` and tests):
 Uses Node `crypto.createVerify` with public key from JWKS:
 
 ```typescript
-verifier.update(options.rawPayload)
-verifier.verify(signingKey, options.signature, signatureFormat)
+authorizer.update(options.rawPayload)
+authorizer.verify(signingKey, options.signature, signatureFormat)
 ```
 
 Throws if any required field is missing:

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # @t4h.framework/jwks
 
+## 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
+
+- [#167](https://github.com/tech4humans-brasil/framework/pull/167) [`1b1509f`](https://github.com/tech4humans-brasil/framework/commit/1b1509f9b6d2554dfab1f7633c3d022249e4fa01) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Moves the callbacks route helpers from `@t4h.framework/webhook` to
+  `@t4h.framework/core`. The route advances any pending async activity, not only
+  `webhook()`, and the core already owned its contract (`AsyncActivityCallbackAuth`,
+  `GetActivityCallbackUrlClaim`, `AsyncActivityAdvanceContext`).
+
+  **core**: new `AsyncActivityCallback` namespace with `deriveToken`, `isTokenValid`,
+  `parseBody`, `getHeader`, `getBearerToken`, `flattenHeaders`, `authorize` and
+  the types `AsyncActivityCallback.Delivery`, `AsyncActivityCallback.Headers`, `AsyncActivityCallback.Json`,
+  `AsyncActivityCallback.AuthType`, `AsyncActivityCallback.Authorizer`, `AsyncActivityCallback.Authorizers`.
+  `AsyncActivityCallback.authorize(auth, request, authorizers?)` ships `basic`, `header` and
+  `bearer`; `hmac` and `jwt` are authorizers the host passes in, so the core does not
+  depend on `@t4h.framework/hmac` or `@t4h.framework/jwks`. A declared type without
+  a authorizer throws `AsyncActivityCallbackAuthorizerMissingException`; an unknown type throws
+  `AsyncActivityCallbackAuthUnsupportedException`.
+
+  **hmac**: new `@t4h.framework/hmac/callback` entry whose default export is the
+  `hmac` callback authorizer, `hmacCallback`.
+
+  **jwks**: new `@t4h.framework/jwks/callback` entry whose default export is the
+  `jwt` callback authorizer, `jwksCallback`.
+
+  **webhook**: no longer exports `deriveCallbackToken`, `isCallbackTokenValid`,
+  `verifyCallbackAuth`, `parseCallbackBody`, `getHeader`, `flattenHeaders` nor
+  `CallbackRequest`/`CallbackHeaders`, and no longer depends on `hmac` and `jwks`;
+  `WebhookJson` is now an alias of the core `AsyncActivityCallback.Json`. Hosts import the
+  helpers from the core `AsyncActivityCallback` namespace and the authorizers from the two entries.
+
+  **dev**: `@t4h.framework/webhook` becomes an optional peer like the other
+  integrations. Only `@t4h.framework/core` is required again, which fixes
+  `ERR_MODULE_NOT_FOUND: Cannot find package '@t4h.framework/webhook'` on
+  projects that never call `webhook()`. `hmac` and `jwt` callback authorizers are
+  loaded from the project when `@t4h.framework/hmac` / `@t4h.framework/jwks` are
+  installed; a callback whose declared `auth` needs a missing package answers 500
+  naming the package to install.
+
+### Patch Changes
+
+- Updated dependencies [[`1b1509f`](https://github.com/tech4humans-brasil/framework/commit/1b1509f9b6d2554dfab1f7633c3d022249e4fa01), [`1b1509f`](https://github.com/tech4humans-brasil/framework/commit/1b1509f9b6d2554dfab1f7633c3d022249e4fa01)]:
+  - @t4h.framework/core@0.13.0
+
 ## 0.5.2
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tech for humans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,6 +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`: 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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,75 @@
+import { AsyncActivityCallback, } from '@t4h.framework/core';
+import jwks from './jwks-authorize.js';
+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 {
+        return await jwks({
+            url: auth.jwksUri,
+            signature: token,
+            rawPayload: '',
+            issuer: auth.issuer,
+            audience: auth.audience,
+        });
+    }
+    catch {
+        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

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

package/dist/jwks.d.ts

@@ -1,3 +1,4 @@
 export * from './jwks-authorize.js';
+export * from './jwks-callback.js';
 export * from './models/JWKSAuthorization.js';
 //# sourceMappingURL=jwks.d.ts.map

package/dist/jwks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../src/jwks.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,+BAA+B,CAAA"}
+{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../src/jwks.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,oBAAoB,CAAA;AAClC,cAAc,+BAA+B,CAAA"}

package/dist/jwks.js

@@ -1,3 +1,4 @@
 export * from './jwks-authorize.js';
+export * from './jwks-callback.js';
 export * from './models/JWKSAuthorization.js';
 //# sourceMappingURL=jwks.js.map

package/dist/jwks.js.map

@@ -1 +1 @@
-{"version":3,"file":"jwks.js","sourceRoot":"","sources":["../src/jwks.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,+BAA+B,CAAA"}
+{"version":3,"file":"jwks.js","sourceRoot":"","sources":["../src/jwks.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,oBAAoB,CAAA;AAClC,cAAc,+BAA+B,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/jwks",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "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",
@@ -20,6 +20,10 @@
     "./authorize": {
       "types": "./dist/jwks-authorize.d.ts",
       "import": "./dist/jwks-authorize.js"
+    },
+    "./callback": {
+      "types": "./dist/jwks-callback.d.ts",
+      "import": "./dist/jwks-callback.js"
     }
   },
   "module": "./dist/jwks.js",
@@ -37,13 +41,13 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.12.0",
+    "@t4h.framework/core": "^0.14.0",
     "@types/jsonwebtoken": "^9",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.12.0"
+    "@t4h.framework/core": "^0.14.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {