@t4h.framework/hmac 0.2.2 → 0.3.0

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

@@ -27,6 +27,7 @@ Package path: `framework/packages/hmac`. See [README.md](../../../README.md) for
 |-------|---------|
 | `@t4h.framework/hmac` | `HMACAuthorization`, `HMACAuthorizationContext`, `HMACAuthorizationManifest`, `HMACAlgorithm`, `HMAC_DEFAULT_ALGORITHM`, `HMAC_DEFAULT_SIGNATURE_FORMAT`, re-exports authorize module |
 | `@t4h.framework/hmac/authorize` | Default async handler: `(context) => Promise<boolean>` |
+| `@t4h.framework/hmac/callback` | Default export `hmacCallback`: `(auth, request) => Promise<boolean>`, the `hmac` authorizer hosts pass to the core `AsyncActivityCallback.authorize` |
 
 ```typescript
 import {

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @t4h.framework/hmac
 
+## 0.3.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.2.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/hmac` | `HMACAuthorization`, `HMACAuthorizationContext`, `HMACAlgorithm`, and related types |
 | `@t4h.framework/hmac/authorize` | Default async handler invoked by the runtime with the manifest context |
+| `@t4h.framework/hmac/callback` | Default export `hmacCallback`: `hmac` callback authorizer for the core `AsyncActivityCallback.authorize` (`pending({ auth: { type: 'hmac' } })`) |
 
 ## `HMACAuthorization`
 

package/dist/hmac-callback.d.ts

@@ -0,0 +1,3 @@
+import { AsyncActivityCallback, type AsyncActivityCallbackAuthHmac } from '@t4h.framework/core';
+export default function hmacCallback(auth: AsyncActivityCallbackAuthHmac, request: AsyncActivityCallback.Delivery): Promise<boolean>;
+//# sourceMappingURL=hmac-callback.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hmac-callback.d.ts","sourceRoot":"","sources":["../src/hmac-callback.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,6BAA6B,EACnC,MAAM,qBAAqB,CAAA;AAI5B,wBAA8B,YAAY,CACxC,IAAI,EAAE,6BAA6B,EACnC,OAAO,EAAE,qBAAqB,CAAC,QAAQ,GACtC,OAAO,CAAC,OAAO,CAAC,CA4BlB"}

package/dist/hmac-callback.js

@@ -0,0 +1,26 @@
+import { AsyncActivityCallback, } from '@t4h.framework/core';
+import hmac from './hmac-authorize.js';
+export default async function hmacCallback(auth, request) {
+    const signature = AsyncActivityCallback.getHeader(request.headers, auth.header);
+    if (!signature)
+        return false;
+    const timestamp = auth.timestampHeader
+        ? AsyncActivityCallback.getHeader(request.headers, auth.timestampHeader)
+        : undefined;
+    if (auth.timestampHeader && !timestamp)
+        return false;
+    const rawPayload = (auth.signedPayload ?? '{body}')
+        .replaceAll('{timestamp}', timestamp ?? '')
+        .replaceAll('{body}', request.rawBody);
+    return hmac({
+        secret: auth.secret,
+        signature,
+        rawPayload,
+        algorithm: auth.algorithm,
+        signatureFormat: auth.signatureFormat,
+        signaturePrefix: auth.signaturePrefix,
+        timestamp,
+        toleranceInSeconds: auth.toleranceInSeconds,
+    });
+}
+//# sourceMappingURL=hmac-callback.js.map

package/dist/hmac-callback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac-callback.js","sourceRoot":"","sources":["../src/hmac-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,IAAmC,EACnC,OAAuC;IAEvC,MAAM,SAAS,GAAG,qBAAqB,CAAC,SAAS,CAC/C,OAAO,CAAC,OAAO,EACf,IAAI,CAAC,MAAM,CACZ,CAAA;IAED,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAA;IAE5B,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe;QACpC,CAAC,CAAC,qBAAqB,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC;QACxE,CAAC,CAAC,SAAS,CAAA;IAEb,IAAI,IAAI,CAAC,eAAe,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAA;IAEpD,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,QAAQ,CAAC;SAChD,UAAU,CAAC,aAAa,EAAE,SAAS,IAAI,EAAE,CAAC;SAC1C,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;IAExC,OAAO,IAAI,CAAC;QACV,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,SAAS;QACT,UAAU;QACV,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,SAAS;QACT,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;KAC5C,CAAC,CAAA;AACJ,CAAC"}

package/dist/hmac.d.ts

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

package/dist/hmac.d.ts.map

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

package/dist/hmac.js

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

package/dist/hmac.js.map

@@ -1 +1 @@
-{"version":3,"file":"hmac.js","sourceRoot":"","sources":["../src/hmac.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,+BAA+B,CAAA"}
+{"version":3,"file":"hmac.js","sourceRoot":"","sources":["../src/hmac.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/hmac",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "HMAC module for the T4H Framework authorization",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/hmac",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -20,6 +20,10 @@
     "./authorize": {
       "types": "./dist/hmac-authorize.d.ts",
       "import": "./dist/hmac-authorize.js"
+    },
+    "./callback": {
+      "types": "./dist/hmac-callback.d.ts",
+      "import": "./dist/hmac-callback.js"
     }
   },
   "module": "./dist/hmac.js",
@@ -37,12 +41,12 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.12.0",
+    "@t4h.framework/core": "^0.13.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.12.0"
+    "@t4h.framework/core": "^0.13.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {