@t4h.framework/hmac 0.0.0-experimental-20260807115832

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

@@ -0,0 +1,247 @@
+---
+name: framework-hmac
+description: >-
+  HMAC shared-secret authorization for T4H Framework workflows and apps. Use
+  when importing @t4h.framework/hmac, wiring HMACAuthorization on Workflow or
+  App, verifying signed webhook bodies (GitHub/Stripe style), configuring
+  algorithm/signatureFormat/signaturePrefix, adding timestamp replay
+  protection, or implementing the @t4h.framework/hmac/authorize runtime
+  handler. Requires @t4h.framework/core. Package path: framework/packages/hmac.
+---
+
+# @t4h.framework/hmac
+
+HMAC-backed **Authorization** for workflows and apps. Exposes `HMACAuthorization` (core manifest) and a default runtime handler at `@t4h.framework/hmac/authorize` that recomputes the HMAC over a raw payload with a shared secret and compares it in constant time.
+
+**Peer dependency:** `@t4h.framework/core` (same major line).
+
+**Node:** `>=22`. No runtime dependencies — verification uses `node:crypto`.
+
+Package path: `framework/packages/hmac`. See [README.md](../../../README.md) for overview.
+
+---
+
+## Imports
+
+| Entry | Purpose |
+|-------|---------|
+| `@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>` |
+
+```typescript
+import {
+  HMACAuthorization,
+  type HMACAuthorizationContext,
+  HMACAlgorithm,
+} from '@t4h.framework/hmac'
+```
+
+Do **not** assume header parsing, env-variable mapping, or provider-specific presets — this package does not read HTTP or env. Your app or hosting layer supplies `secret`, `signature`, `rawPayload` and `timestamp`.
+
+---
+
+## Wiring authorization (core)
+
+`HMACAuthorization` extends core `Authorization`. Attach to a **Workflow** or **App**; `toManifest()` registers the handler module for the platform.
+
+```typescript
+import { App, Workflow } from '@t4h.framework/core'
+import { HMACAuthorization } from '@t4h.framework/hmac'
+
+const authorization = new HMACAuthorization({
+  secret: '<shared-secret>',
+  signature: '<signature-from-runtime>',
+  rawPayload: '<exact-signed-bytes>',
+  signaturePrefix: 'sha256=',
+})
+
+const workflow = new Workflow(
+  { id: 'protected/v1', authorization },
+  async () => ({ ok: true }),
+)
+
+const app = new App({
+  id: 'my-app',
+  workflows: [workflow],
+  authorization, // optional app-level default
+})
+```
+
+Manifest shape (from tests):
+
+```typescript
+{
+  pathToModule: '@t4h.framework/hmac/authorize',
+  context: {
+    secret: string
+    signature: string
+    rawPayload: string
+    algorithm?: string
+    signatureFormat?: string
+    signaturePrefix?: string
+    timestamp?: string
+    toleranceInSeconds?: number
+  },
+}
+```
+
+Optional manifest fields are still present as `undefined` when omitted (`toManifest` copies all keys).
+
+---
+
+## Context: `HMACAuthorizationContext`
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `secret` | Yes | Shared secret, used as **UTF-8 bytes** for the HMAC key. Empty → **throws**. A secret delivered hex/base64-encoded must be decoded by the caller before it is passed in. |
+| `signature` | Yes | Signature the caller presented. Empty string → handler returns `false`. |
+| `rawPayload` | Yes | The **exact** bytes that were signed. Never re-serialize parsed JSON — key order and whitespace change and the digest will not match. |
+| `algorithm` | No | **Enum key** on `HMACAlgorithm` (`SHA1`, `SHA256`, `SHA384`, `SHA512`), not the Node crypto string. Defaults to `SHA256`. |
+| `signatureFormat` | No | Encoding of `signature`: `hex`, `base64`, `base64url`, `binary`. Defaults to `hex`. |
+| `signaturePrefix` | No | Stripped before comparison, e.g. `sha256=`. If set and absent from `signature` → `false`. |
+| `timestamp` | Conditional | Required when `toleranceInSeconds` is set. All-digit string → Unix **seconds**; otherwise `Date.parse` (ISO 8601). |
+| `toleranceInSeconds` | No | Enables replay protection. Symmetric window (past **and** future, for clock skew). |
+
+---
+
+## Runtime handler (`@t4h.framework/hmac/authorize`)
+
+Default export:
+
+```typescript
+(options: HMACAuthorizationContext) => Promise<boolean>
+```
+
+Behavior, in order (from `hmac-authorize.ts` and tests):
+
+1. Falsy `signature` → **`false`** (no throw).
+2. Falsy `secret` → **throw** `Secret is required for payload verification`.
+3. Resolve `algorithm` via `HMACAlgorithm[key]`; unknown key → **throw** `Unsupported algorithm: <value>`.
+4. Resolve `signatureFormat`; not one of `hex`/`base64`/`base64url`/`binary` → **throw** `Unsupported signature format: <value>`.
+5. If `toleranceInSeconds` is set: missing `timestamp` → **throw** `Timestamp is required when a tolerance is set`; outside the window or unparseable → **`false`**.
+6. If `signaturePrefix` is set and `signature` does not start with it → **`false`**; otherwise strip it.
+7. Compute `crypto.createHmac(algorithm, secret).update(rawPayload).digest()` and compare with `crypto.timingSafeEqual`.
+
+The candidate is decoded from `signatureFormat` into a Buffer before comparing, so **hex casing and base64 padding never cause a false negative**, and a candidate of a different decoded length short-circuits to `false` (`timingSafeEqual` throws on length mismatch).
+
+```typescript
+export enum HMACAlgorithm {
+  SHA1 = 'sha1',
+  SHA256 = 'sha256',
+  SHA384 = 'sha384',
+  SHA512 = 'sha512',
+}
+```
+
+Pass `algorithm: 'SHA256'`, not `'sha256'` — the lowercase form is the enum *value* and makes the handler throw.
+
+---
+
+## Examples
+
+### Webhook with a prefixed hex signature (GitHub style)
+
+```typescript
+new HMACAuthorization({
+  secret: env.WEBHOOK_SECRET,
+  signature: request.headers['x-hub-signature-256'], // 'sha256=9f86d0…'
+  rawPayload: rawRequestBody,                        // the untouched body string
+  signaturePrefix: 'sha256=',
+})
+```
+
+### Timestamped payload with replay protection (Stripe style)
+
+```typescript
+new HMACAuthorization({
+  secret: env.WEBHOOK_SECRET,
+  signature: parsedSignatureHeader.v1,
+  rawPayload: `${timestamp}.${rawRequestBody}`, // timestamp bound INTO the signature
+  timestamp,
+  toleranceInSeconds: 300,
+})
+```
+
+`toleranceInSeconds` only proves the timestamp is *recent*. Including the timestamp in `rawPayload` is what stops an attacker from editing it — do both.
+
+### Base64 SHA512
+
+```typescript
+new HMACAuthorization({
+  secret: env.WEBHOOK_SECRET,
+  signature: base64Signature,
+  rawPayload: canonicalPayloadString,
+  algorithm: 'SHA512',
+  signatureFormat: 'base64',
+})
+```
+
+---
+
+## Return values vs errors
+
+| Situation | Result |
+|-----------|--------|
+| Empty `signature` | `false` |
+| Digest matches | `true` |
+| Wrong secret / tampered payload / wrong algorithm / garbage signature | `false` |
+| `signaturePrefix` set but missing from `signature` | `false` |
+| Timestamp outside tolerance, or not parseable | `false` |
+| Empty `secret` | **Throw** |
+| `algorithm` not a `HMACAlgorithm` key | **Throw** |
+| Unsupported `signatureFormat` | **Throw** |
+| `toleranceInSeconds` without `timestamp` | **Throw** |
+
+Design callers so manifest context is complete **before** the handler runs; missing or malformed configuration is a programmer error, not a silent denial.
+
+---
+
+## Testing the handler locally
+
+Tests sign with real `node:crypto` HMACs — no mocking needed, since verification is a local computation.
+
+```typescript
+import crypto from 'node:crypto'
+import hmac from '@t4h.framework/hmac/authorize'
+
+const payload = '{"event":"order.created"}'
+const signature = crypto
+  .createHmac('sha256', 'super-secret')
+  .update(payload)
+  .digest('hex')
+
+await expect(
+  hmac({ secret: 'super-secret', signature, rawPayload: payload }),
+).resolves.toBe(true)
+```
+
+Use `vi.useFakeTimers()` + `vi.setSystemTime(...)` for the tolerance tests — `isWithinTolerance` reads `Date.now()`.
+
+Test files: `src/__tests__/hmac-authorize.spec.ts`, `src/helpers/__tests__/timingSafeCompare.spec.ts`, `src/helpers/__tests__/isWithinTolerance.spec.ts`, `src/models/__tests__/HMACAuthorization.spec.ts`.
+
+---
+
+## What this package does not do
+
+- No HTTP header / query / env extraction for signatures or secrets.
+- No provider presets (no built-in GitHub/Stripe/Shopify header parsing) — you assemble `rawPayload` and pass the header value in.
+- No public-key signatures — for those use **framework-jwks**.
+- No secret decoding: `secret` is used as UTF-8 bytes as given.
+- Does not define **Claims** or **Activities** — only **Authorization** manifests for core `Workflow` / `App`.
+
+For workflow orchestration and claims use **framework-core**; for JWKS/JWT verification use **framework-jwks**; for OIDC introspection use **framework-oidc**.
+
+---
+
+## Quick checklist for agents
+
+1. Add `@t4h.framework/hmac` and peer `@t4h.framework/core`.
+2. Build `HMACAuthorizationContext` with `secret`, `signature`, `rawPayload` at minimum.
+3. Attach `new HMACAuthorization(context)` to `Workflow` and/or `App` `authorization` option.
+4. Keep `rawPayload` byte-exact — do not parse and re-stringify JSON.
+5. Set `signaturePrefix` when the provider prefixes the header (`sha256=`).
+6. Set `algorithm` / `signatureFormat` only when they differ from `SHA256` / `hex`; use **enum keys**.
+7. Add `timestamp` + `toleranceInSeconds` for replay protection, and bind the timestamp into `rawPayload`.
+8. Read the secret from `EnvDesign` in `src/constants/environments.ts`, never hard-code it.
+9. Expect `false` for deny, throws for misconfiguration.
+10. Do not reference APIs absent from `src/` and tests.

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @t4h.framework/hmac
+
+## 0.0.0-experimental-20260807115832
+
+### Minor Changes
+
+- [#128](https://github.com/tech4humans-brasil/framework/pull/128) [`0107c3b`](https://github.com/tech4humans-brasil/framework/commit/0107c3b8a76a0c96f51f21d7c1c8bd5a76c5c69c) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Create HMAC package for authorization
+
+- [#128](https://github.com/tech4humans-brasil/framework/pull/128) [`0107c3b`](https://github.com/tech4humans-brasil/framework/commit/0107c3b8a76a0c96f51f21d7c1c8bd5a76c5c69c) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Initialize package

package/README.md

@@ -0,0 +1,72 @@
+# @t4h.framework/hmac
+
+HMAC-backed authorization for the T4H Framework. It exposes a core `Authorization` manifest and a runtime handler that verifies a shared-secret signature over a raw payload.
+
+## Peer dependency
+
+Requires `@t4h.framework/core` (same major line as this package).
+
+## Exports
+
+| Entry            | Purpose |
+|------------------|---------|
+| `@t4h.framework/hmac` | `HMACAuthorization`, `HMACAuthorizationContext`, `HMACAlgorithm`, and related types |
+| `@t4h.framework/hmac/authorize` | Default async handler invoked by the runtime with the manifest context |
+
+## `HMACAuthorization`
+
+Subclass of [`Authorization`](https://github.com/tech4humans-brasil/framework/tree/main/packages/core) from core. `toManifest()` points the runtime at `@t4h.framework/hmac/authorize` and passes an `HMACAuthorizationContext`.
+
+Construct it with a full `HMACAuthorizationContext`. How you obtain `signature`, `rawPayload` and `timestamp` — headers, query, body, env — is up to your app and deployment pipeline; this package does not read HTTP or env by itself.
+
+## Context: `HMACAuthorizationContext`
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `secret` | Yes | Shared secret, used as UTF-8 bytes for the HMAC key. Empty string **throws**. |
+| `signature` | Yes | The signature the caller presented. Empty string yields `false`. |
+| `rawPayload` | Yes | The exact bytes that were signed. |
+| `algorithm` | No | A **key** of `HMACAlgorithm` (`'SHA1'`, `'SHA256'`, `'SHA384'`, `'SHA512'`). Defaults to `'SHA256'`. |
+| `signatureFormat` | No | Encoding of `signature`: `'hex'`, `'base64'`, `'base64url'` or `'binary'`. Defaults to `'hex'`. |
+| `signaturePrefix` | No | Prefix to strip before comparing, e.g. `'sha256='` for GitHub-style headers. |
+| `timestamp` | Conditional | When the payload was signed. Required if `toleranceInSeconds` is set. |
+| `toleranceInSeconds` | No | Enables replay protection: rejects signatures whose `timestamp` drifts further than this from now. |
+
+## Runtime handler (`hmac/authorize`)
+
+The default export is an async function:
+
+```ts
+(options: HMACAuthorizationContext) => Promise<boolean>
+```
+
+It recomputes `HMAC(secret, rawPayload)` with the chosen algorithm and compares it against `signature` using `crypto.timingSafeEqual`, so a wrong signature never leaks how many leading bytes were right.
+
+- Returns `false` if `signature` is missing, the digests differ, the expected prefix is absent, or the timestamp is outside the tolerance window.
+- Returns `true` if the digests match.
+- **Throws** on configuration errors: empty `secret`, an `algorithm` that is not a `HMACAlgorithm` key, an unsupported `signatureFormat`, or a `toleranceInSeconds` set without a `timestamp`.
+
+The signature is decoded from `signatureFormat` before the comparison, so hex casing and base64 padding differences never cause a false negative.
+
+### Replay protection
+
+Set `toleranceInSeconds` together with `timestamp` to reject stale signatures. `timestamp` is read as Unix time in seconds when it is all digits, otherwise via `Date.parse` (ISO 8601, for example). The window is symmetric — a sender whose clock runs slightly fast is accepted the same way a slightly slow one is.
+
+Note that the timestamp is only checked for freshness. If you want it *bound* to the signature (so an attacker cannot change it), include it in `rawPayload` the same way the sender did — for example `` `${timestamp}.${body}` ``.
+
+## Example
+
+```typescript
+import { HMACAuthorization } from '@t4h.framework/hmac'
+
+const authorization = new HMACAuthorization({
+  secret: '<shared-secret>',
+  signature: '<signature-from-the-request-header>',
+  rawPayload: '<the-exact-request-body>',
+  signaturePrefix: 'sha256=',
+  timestamp: '<timestamp-from-the-request-header>',
+  toleranceInSeconds: 300,
+})
+```
+
+Wire `authorization` on an `App` or `Workflow` per the core package. The platform loads `@t4h.framework/hmac/authorize` with the manifest context when a protected workflow runs.

package/dist/helpers/isWithinTolerance.d.ts

@@ -0,0 +1,2 @@
+export declare function isWithinTolerance(timestamp: string, toleranceInSeconds: number): boolean;
+//# sourceMappingURL=isWithinTolerance.d.ts.map

package/dist/helpers/isWithinTolerance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isWithinTolerance.d.ts","sourceRoot":"","sources":["../../src/helpers/isWithinTolerance.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAQT"}

package/dist/helpers/isWithinTolerance.js

@@ -0,0 +1,17 @@
+export function isWithinTolerance(timestamp, toleranceInSeconds) {
+    const signedAt = parseTimestamp(timestamp);
+    if (signedAt === null)
+        return false;
+    const driftInSeconds = Math.abs(Date.now() - signedAt) / 1000;
+    return driftInSeconds <= toleranceInSeconds;
+}
+function parseTimestamp(timestamp) {
+    const value = timestamp.trim();
+    if (!value)
+        return null;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+//# sourceMappingURL=isWithinTolerance.js.map

package/dist/helpers/isWithinTolerance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isWithinTolerance.js","sourceRoot":"","sources":["../../src/helpers/isWithinTolerance.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,kBAA0B;IAE1B,MAAM,QAAQ,GAAG,cAAc,CAAC,SAAS,CAAC,CAAA;IAE1C,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAEnC,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,GAAG,IAAI,CAAA;IAE7D,OAAO,cAAc,IAAI,kBAAkB,CAAA;AAC7C,CAAC;AAED,SAAS,cAAc,CAAC,SAAiB;IACvC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAA;IAE9B,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IAEvB,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAA;IAEpD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAEhC,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAA;AAC7C,CAAC"}

package/dist/helpers/timingSafeCompare.d.ts

@@ -0,0 +1,3 @@
+import { type BinaryToTextEncoding } from 'node:crypto';
+export declare function timingSafeCompare(expected: Buffer, candidate: string, signatureFormat: BinaryToTextEncoding): boolean;
+//# sourceMappingURL=timingSafeCompare.d.ts.map

package/dist/helpers/timingSafeCompare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timingSafeCompare.d.ts","sourceRoot":"","sources":["../../src/helpers/timingSafeCompare.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAE/D,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,oBAAoB,GACpC,OAAO,CAMT"}

package/dist/helpers/timingSafeCompare.js

@@ -0,0 +1,8 @@
+import crypto, {} from 'node:crypto';
+export function timingSafeCompare(expected, candidate, signatureFormat) {
+    const provided = Buffer.from(candidate, signatureFormat);
+    if (provided.length !== expected.length)
+        return false;
+    return crypto.timingSafeEqual(expected, provided);
+}
+//# sourceMappingURL=timingSafeCompare.js.map

package/dist/helpers/timingSafeCompare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timingSafeCompare.js","sourceRoot":"","sources":["../../src/helpers/timingSafeCompare.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAA6B,MAAM,aAAa,CAAA;AAE/D,MAAM,UAAU,iBAAiB,CAC/B,QAAgB,EAChB,SAAiB,EACjB,eAAqC;IAErC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,CAAA;IAExD,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAErD,OAAO,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;AACnD,CAAC"}

package/dist/hmac-authorize.d.ts

@@ -0,0 +1,11 @@
+import type { HMACAuthorizationContext } from './models/HMACAuthorization.js';
+export declare enum HMACAlgorithm {
+    SHA1 = "sha1",
+    SHA256 = "sha256",
+    SHA384 = "sha384",
+    SHA512 = "sha512"
+}
+export declare const HMAC_DEFAULT_ALGORITHM = "SHA256";
+export declare const HMAC_DEFAULT_SIGNATURE_FORMAT = "hex";
+export default function hmac(options: HMACAuthorizationContext): Promise<boolean>;
+//# sourceMappingURL=hmac-authorize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hmac-authorize.d.ts","sourceRoot":"","sources":["../src/hmac-authorize.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAE7E,oBAAY,aAAa;IACvB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAED,eAAO,MAAM,sBAAsB,WAAW,CAAA;AAE9C,eAAO,MAAM,6BAA6B,QAAQ,CAAA;AASlD,wBAA8B,IAAI,CAChC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC,CAgDlB"}

package/dist/hmac-authorize.js

@@ -0,0 +1,51 @@
+import crypto, {} from 'node:crypto';
+import { isWithinTolerance } from './helpers/isWithinTolerance.js';
+import { timingSafeCompare } from './helpers/timingSafeCompare.js';
+export var HMACAlgorithm;
+(function (HMACAlgorithm) {
+    HMACAlgorithm["SHA1"] = "sha1";
+    HMACAlgorithm["SHA256"] = "sha256";
+    HMACAlgorithm["SHA384"] = "sha384";
+    HMACAlgorithm["SHA512"] = "sha512";
+})(HMACAlgorithm || (HMACAlgorithm = {}));
+export const HMAC_DEFAULT_ALGORITHM = 'SHA256';
+export const HMAC_DEFAULT_SIGNATURE_FORMAT = 'hex';
+const SIGNATURE_FORMATS = [
+    'hex',
+    'base64',
+    'base64url',
+    'binary',
+];
+export default async function hmac(options) {
+    const signature = options.signature;
+    if (!signature)
+        return false;
+    const secret = options.secret;
+    if (!secret)
+        throw new Error('Secret is required for payload verification');
+    const algorithmKey = options.algorithm ?? HMAC_DEFAULT_ALGORITHM;
+    const algorithm = HMACAlgorithm[algorithmKey];
+    if (!algorithm)
+        throw new Error(`Unsupported algorithm: ${algorithmKey}`);
+    const signatureFormat = options.signatureFormat ?? HMAC_DEFAULT_SIGNATURE_FORMAT;
+    if (!SIGNATURE_FORMATS.includes(signatureFormat))
+        throw new Error(`Unsupported signature format: ${signatureFormat}`);
+    const toleranceInSeconds = options.toleranceInSeconds;
+    if (toleranceInSeconds !== undefined) {
+        const timestamp = options.timestamp;
+        if (!timestamp)
+            throw new Error('Timestamp is required when a tolerance is set');
+        if (!isWithinTolerance(timestamp, toleranceInSeconds))
+            return false;
+    }
+    const prefix = options.signaturePrefix;
+    if (prefix && !signature.startsWith(prefix))
+        return false;
+    const candidate = prefix ? signature.slice(prefix.length) : signature;
+    const expected = crypto
+        .createHmac(algorithm, secret)
+        .update(options.rawPayload)
+        .digest();
+    return timingSafeCompare(expected, candidate, signatureFormat);
+}
+//# sourceMappingURL=hmac-authorize.js.map

package/dist/hmac-authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac-authorize.js","sourceRoot":"","sources":["../src/hmac-authorize.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAA6B,MAAM,aAAa,CAAA;AAE/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAA;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAA;AAGlE,MAAM,CAAN,IAAY,aAKX;AALD,WAAY,aAAa;IACvB,8BAAa,CAAA;IACb,kCAAiB,CAAA;IACjB,kCAAiB,CAAA;IACjB,kCAAiB,CAAA;AACnB,CAAC,EALW,aAAa,KAAb,aAAa,QAKxB;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,QAAQ,CAAA;AAE9C,MAAM,CAAC,MAAM,6BAA6B,GAAG,KAAK,CAAA;AAElD,MAAM,iBAAiB,GAA2B;IAChD,KAAK;IACL,QAAQ;IACR,WAAW;IACX,QAAQ;CACT,CAAA;AAED,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,IAAI,CAChC,OAAiC;IAEjC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;IAEnC,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAA;IAE5B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;IAE7B,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IAE3E,MAAM,YAAY,GAAG,OAAO,CAAC,SAAS,IAAI,sBAAsB,CAAA;IAEhE,MAAM,SAAS,GAAG,aAAa,CAAC,YAA0C,CAAC,CAAA;IAE3E,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,YAAY,EAAE,CAAC,CAAA;IAEzE,MAAM,eAAe,GACnB,OAAO,CAAC,eAAe,IAAI,6BAA6B,CAAA;IAE1D,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,eAAuC,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,iCAAiC,eAAe,EAAE,CAAC,CAAA;IAErE,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAA;IAErD,IAAI,kBAAkB,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;QAEnC,IAAI,CAAC,SAAS;YACZ,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;QAElE,IAAI,CAAC,iBAAiB,CAAC,SAAS,EAAE,kBAAkB,CAAC;YAAE,OAAO,KAAK,CAAA;IACrE,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,eAAe,CAAA;IAEtC,IAAI,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAA;IAEzD,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAErE,MAAM,QAAQ,GAAG,MAAM;SACpB,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC;SAC7B,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;SAC1B,MAAM,EAAE,CAAA;IAEX,OAAO,iBAAiB,CACtB,QAAQ,EACR,SAAS,EACT,eAAuC,CACxC,CAAA;AACH,CAAC"}

package/dist/hmac.d.ts

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

package/dist/hmac.d.ts.map

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

package/dist/hmac.js

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

package/dist/hmac.js.map

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

package/dist/models/HMACAuthorization.d.ts

@@ -0,0 +1,19 @@
+import type { BinaryToTextEncoding } from 'node:crypto';
+import { Authorization, type AuthorizationManifest } from '@t4h.framework/core';
+export type HMACAuthorizationContext = {
+    secret: string;
+    signature: string;
+    rawPayload: string;
+    algorithm?: string;
+    signatureFormat?: BinaryToTextEncoding | string;
+    signaturePrefix?: string;
+    timestamp?: string;
+    toleranceInSeconds?: number;
+};
+export type HMACAuthorizationManifest = AuthorizationManifest<HMACAuthorizationContext>;
+export declare class HMACAuthorization extends Authorization<HMACAuthorizationContext> {
+    private readonly context;
+    constructor(context: HMACAuthorizationContext);
+    toManifest(): HMACAuthorizationManifest;
+}
+//# sourceMappingURL=HMACAuthorization.d.ts.map

package/dist/models/HMACAuthorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HMACAuthorization.d.ts","sourceRoot":"","sources":["../../src/models/HMACAuthorization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAEvD,OAAO,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAE/E,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,eAAe,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAAA;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,yBAAyB,GACnC,qBAAqB,CAAC,wBAAwB,CAAC,CAAA;AAEjD,qBAAa,iBAAkB,SAAQ,aAAa,CAAC,wBAAwB,CAAC;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,wBAAwB;IAIvD,UAAU,IAAI,yBAAyB;CAe/C"}

package/dist/models/HMACAuthorization.js

@@ -0,0 +1,24 @@
+import { Authorization } from '@t4h.framework/core';
+export class HMACAuthorization extends Authorization {
+    context;
+    constructor(context) {
+        super();
+        this.context = context;
+    }
+    toManifest() {
+        return {
+            context: {
+                secret: this.context.secret,
+                signature: this.context.signature,
+                rawPayload: this.context.rawPayload,
+                algorithm: this.context.algorithm,
+                signatureFormat: this.context.signatureFormat,
+                signaturePrefix: this.context.signaturePrefix,
+                timestamp: this.context.timestamp,
+                toleranceInSeconds: this.context.toleranceInSeconds,
+            },
+            pathToModule: '@t4h.framework/hmac/authorize',
+        };
+    }
+}
+//# sourceMappingURL=HMACAuthorization.js.map

package/dist/models/HMACAuthorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HMACAuthorization.js","sourceRoot":"","sources":["../../src/models/HMACAuthorization.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAA8B,MAAM,qBAAqB,CAAA;AAgB/E,MAAM,OAAO,iBAAkB,SAAQ,aAAuC;IAC/C;IAA7B,YAA6B,OAAiC;QAC5D,KAAK,EAAE,CAAA;QADoB,YAAO,GAAP,OAAO,CAA0B;IAE9D,CAAC;IAEM,UAAU;QACf,OAAO;YACL,OAAO,EAAE;gBACP,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;gBAC3B,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS;gBACjC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU;gBACnC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS;gBACjC,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe;gBAC7C,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe;gBAC7C,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS;gBACjC,kBAAkB,EAAE,IAAI,CAAC,OAAO,CAAC,kBAAkB;aACpD;YACD,YAAY,EAAE,+BAA+B;SAC9C,CAAA;IACH,CAAC;CACF"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@t4h.framework/hmac",
+  "version": "0.0.0-experimental-20260807115832",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tech4humans-brasil/framework.git",
+    "directory": "packages/hmac"
+  },
+  "license": "MIT",
+  "author": "Tech4Humans <contact@tech4h.com.br> (https://tech4h.com.br)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/hmac.d.ts",
+      "import": "./dist/hmac.js"
+    },
+    "./authorize": {
+      "types": "./dist/hmac-authorize.d.ts",
+      "import": "./dist/hmac-authorize.js"
+    }
+  },
+  "module": "./dist/hmac.js",
+  "types": "./dist/hmac.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    ".ai"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "yarn build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@t4h.framework/core": "^0.9.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@t4h.framework/core": "^0.9.0"
+  },
+  "packageManager": "yarn@4.12.0",
+  "engines": {
+    "node": ">=22"
+  }
+}