@t4h.framework/hmac 0.3.7 → 0.3.9

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

@@ -1,248 +1,119 @@
 ---
 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.
+  Verifies shared-secret HMAC signatures with @t4h.framework/hmac. Use when a
+  T4H Framework workflow or App needs HMACAuthorization, when an async activity
+  such as webhook() declares auth { type: 'hmac' } for its callbacks, or when
+  the user mentions a signed webhook body (GitHub, Shopify, Slack style),
+  HMACAlgorithm, signatureFormat, signaturePrefix, signedPayload, timestamp
+  replay protection or toleranceInSeconds.
 ---
 
 # @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.
+The package has two uses. Pick the one that matches the task:
 
-**Peer dependency:** `@t4h.framework/core` (same major line).
+- **Protect a workflow or an `App`**: `new HMACAuthorization(context)`.
+- **Verify the callbacks of an async activity**: declare
+  `auth: { type: 'hmac', … }` on the activity (for `webhook()`, see the
+  **framework-webhook** skill). The host verifies each callback with
+  `@t4h.framework/hmac/callback`. You do not import it.
 
-**Node:** `>=22`. No runtime dependencies — verification uses `node:crypto`.
+## Protect a workflow or an App
 
-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>` |
-| `@t4h.framework/hmac/callback` | Default export `hmacCallback`: `(auth, request) => Promise<boolean>`, the `hmac` authorizer hosts pass to the core `AsyncActivityCallback.authorize` |
-
-```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.
+1. Declare the secret with `type: String` in the `EnvDesign` in
+   `src/constants/environments.ts`. `HMACAuthorizationContext.secret` is a
+   `string`, not a `Secret`.
+2. Construct the authorization and attach it to the `authorization` option of
+   a `Workflow` or an `App`.
 
 ```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):
+import { environments } from '../constants/environments.js'
 
-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
+export const authorization = new HMACAuthorization({
+  secret: environments.HMAC_SECRET,
+  signature: '<signature-from-the-request-header>',
+  rawPayload: '<the-exact-request-body>',
   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.
+## Verify async activity callbacks
 
-### Base64 SHA512
+The `auth` object names request headers, not values. Its `secret` IS a
+`Secret`: declare it with `type: Secret` and pass it whole.
 
 ```typescript
-new HMACAuthorization({
-  secret: env.WEBHOOK_SECRET,
-  signature: base64Signature,
-  rawPayload: canonicalPayloadString,
-  algorithm: 'SHA512',
-  signatureFormat: 'base64',
-})
+auth: {
+  type: 'hmac',
+  secret: environments.PARTNER_SECRET,
+  header: 'x-slack-signature',
+  signaturePrefix: 'v0=',
+  timestampHeader: 'x-slack-request-timestamp',
+  toleranceInSeconds: 300,
+  signedPayload: 'v0:{timestamp}:{body}',
+}
 ```
 
----
-
-## 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.
+`signedPayload` is a template with `{body}` (raw body) and `{timestamp}`. It
+defaults to `'{body}'`.
+
+## Traps
+
+- `algorithm` is an enum KEY in upper case: `'SHA256'`, not `'sha256'`. Other
+  values throw. Defaults: `'SHA256'` and `'hex'`.
+- `rawPayload` is the exact signed bytes. Do not parse JSON and stringify it
+  again: key order and spaces change and the digest fails.
+- `secret` is used as UTF-8 bytes. Decode a hex or base64 secret first.
+- A literal string in `secret` fails the lint rule
+  `no-literal-secret-in-authorization` of `@t4h.framework/core`.
+- An all-digit `timestamp` is Unix SECONDS. A millisecond value is read as
+  seconds and fails the tolerance check. Other strings go through
+  `Date.parse`.
+- The tolerance check only proves the timestamp is recent. Put the timestamp in
+  the signed bytes too (`rawPayload` or `signedPayload`), or an attacker can
+  change it.
+- On a callback, `toleranceInSeconds` without `timestampHeader` makes each
+  callback fail with an error.
+- A denied caller gives `false`. A configuration mistake (empty `secret`,
+  unknown `algorithm` or `signatureFormat`, tolerance without timestamp)
+  throws.
+- `signatureFormat` `'binary'` exists only on `HMACAuthorization`, not on the
+  callback `auth`.
+
+## Test
+
+Sign with `node:crypto` and call the default export of
+`@t4h.framework/hmac/authorize`. No mock is necessary:
 
 ```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')
+  .createHmac('sha256', 'test-secret')
   .update(payload)
   .digest('hex')
 
 await expect(
-  hmac({ secret: 'super-secret', signature, rawPayload: payload }),
+  hmac({ secret: 'test-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`.
+For a tolerance test, set the clock with `vi.useFakeTimers()` and
+`vi.setSystemTime(...)`.
 
----
-
-## What this package does not do
+## Related skills
 
-- 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`.
+- **framework-jwks**: public-key signatures and JWTs.
+- **framework-webhook**: wait for a partner callback that uses this `auth`.
 
-For workflow orchestration and claims use **framework-core**; for JWKS/JWT verification use **framework-jwks**; for OIDC introspection use **framework-oidc**.
-
----
+## Reference
 
-## 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.
+- Guide: <https://tech4humans-brasil.github.io/framework/hmac/>
+- Types: `node_modules/@t4h.framework/hmac/dist/hmac.d.ts`
+- Callback `auth` type: `AsyncActivityCallbackAuthHmac` in
+  `node_modules/@t4h.framework/core/dist/`

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @t4h.framework/hmac
 
+## 0.3.9
+
+### Patch Changes
+
+- [#257](https://github.com/tech4humans-brasil/framework/pull/257) [`586bfb4`](https://github.com/tech4humans-brasil/framework/commit/586bfb4663f4a478527ee0c8db360603f034d615) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The hmac README is now short and links to the site. The site page now describes the callback `auth`, the results and errors, and how to test the handler.
+
+## 0.3.8
+
+### Patch Changes
+
+- [#241](https://github.com/tech4humans-brasil/framework/pull/241) [`f6b8454`](https://github.com/tech4humans-brasil/framework/commit/f6b845484d22e7c8e7240fe2e113f1cdea7c8ce3) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Adds seven rules to `@t4h.framework/core/eslint` and turns them on in `configs.recommended`:
+  - `no-io-in-workflow` reports `fetch` and calls to network, file, database and mail modules in a workflow and in the `constructor`, `toInput` and `toOutput` of an activity. It also reports `zlib` and `stream` calls there, because they work on the content in memory on each replay.
+  - `no-binary-subclass` reports a class that extends `Binary`.
+  - `no-framework-activity-in-app` reports `new` and `extends` on an activity of a framework package other than the core.
+  - `no-testing-import-in-source` reports an import of a `@t4h.framework/<package>/testing` entry out of a test file.
+  - `require-workflow-id` reports a `Workflow` with no `id`.
+  - `no-secret-to-string` reports a `Secret` that becomes a string.
+  - `no-literal-secret-in-authorization` reports a string literal in the `secret` or `clientSecret` field of an `Authorization`.
+
+  The package skills now name these rules in place of the text that the rules enforce. The docs and skills give each `Workflow` an `id`, read the HMAC secret from `EnvDesign`, and do not document a custom HTTP activity.
+
+- [#243](https://github.com/tech4humans-brasil/framework/pull/243) [`0ffd663`](https://github.com/tech4humans-brasil/framework/commit/0ffd663ce8369edd7b54206cb3216568ad1de471) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The README examples read each value from `environments`, an `EnvDesign` in `src/constants/environments.ts`, and pass each credential as a `Secret`. They no longer use `process.env`, the raw `env` from the core or a literal in a `Secret` field. The jwks README describes the real context fields (`signature`, `rawPayload`) and says that a token that `jwt.verify` rejects throws.
+
+- [#240](https://github.com/tech4humans-brasil/framework/pull/240) [`0606115`](https://github.com/tech4humans-brasil/framework/commit/0606115e2e0baa994e9f0ed3559ee54ecac88e44) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The skills do not repeat a rule that a lint rule, `tsc` or a runtime error already enforces. Each such rule is now one line that names the gate. The examples that broke a gate (`process.env`, `as any`, an inline secret, an `EnvDesign` in a workflow file, `ref.output` before `wait()`) are correct now.
+
+- [#228](https://github.com/tech4humans-brasil/framework/pull/228) [`d29e1ab`](https://github.com/tech4humans-brasil/framework/commit/d29e1ab29a039b13c3e4b075472bd615566ae75e) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Uses exact types and `unknown` in place of `any`, and checks external data with guards.
+  - harness: the fix-issues prompt lists each sensor as `- checkTypes: PASS`. Before, it printed `- 0: [object Object]`.
+  - hmac: an algorithm name such as `constructor` throws `Unsupported algorithm`.
+  - oidc: a discovery response with no `introspection_endpoint`, or a null introspection body, throws a clear error.
+  - `HttpRequestActivity.toOutput` takes `HttpRequestActivityOutput` in place of `any`.
+
 ## 0.3.7
 
 ## 0.3.6

package/README.md

@@ -1,73 +1,34 @@
 # @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.
+HMAC authorization for the T4H Framework. It verifies a shared-secret signature
+over a raw payload, for a workflow, an app or the callbacks of an async
+activity.
 
-## Peer dependency
+## Install
 
-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 |
-| `@t4h.framework/hmac/callback` | Default export `hmacCallback`: `hmac` callback authorizer for the core `AsyncActivityCallback.authorize` (`pending({ auth: { type: 'hmac' } })`) |
-
-## `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>
+```bash
+npm install @t4h.framework/hmac @t4h.framework/core
 ```
 
-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
+## Usage
 
 ```typescript
 import { HMACAuthorization } from '@t4h.framework/hmac'
 
+import { environments } from './constants/environments.js'
+
 const authorization = new HMACAuthorization({
-  secret: '<shared-secret>',
+  secret: environments.HMAC_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.
+Declare `HMAC_SECRET` with `type: String` in the `EnvDesign` in
+`src/constants/environments.ts`, and attach `authorization` to a `Workflow` or
+an `App`.
+
+## Documentation
+
+<https://tech4humans-brasil.github.io/framework/hmac/>

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

@@ -1 +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"}
+{"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;AAgElD,MAAM,CAAC,OAAO,UAAU,IAAI,CAC1B,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC,CAIlB"}

package/dist/hmac-authorize.js

@@ -16,7 +16,13 @@ const SIGNATURE_FORMATS = [
     'base64url',
     'binary',
 ];
-export default async function hmac(options) {
+function isAlgorithmKey(key) {
+    return Object.hasOwn(HMACAlgorithm, key);
+}
+function isSignatureFormat(format) {
+    return SIGNATURE_FORMATS.some(supported => supported === format);
+}
+function verifyHmac(options) {
     const signature = options.signature;
     if (!signature)
         return false;
@@ -24,11 +30,11 @@ export default async function hmac(options) {
     if (!secret)
         throw new Error('Secret is required for payload verification');
     const algorithmKey = options.algorithm ?? HMAC_DEFAULT_ALGORITHM;
-    const algorithm = HMACAlgorithm[algorithmKey];
-    if (!algorithm)
+    if (!isAlgorithmKey(algorithmKey))
         throw new Error(`Unsupported algorithm: ${algorithmKey}`);
+    const algorithm = HMACAlgorithm[algorithmKey];
     const signatureFormat = options.signatureFormat ?? HMAC_DEFAULT_SIGNATURE_FORMAT;
-    if (!SIGNATURE_FORMATS.includes(signatureFormat))
+    if (!isSignatureFormat(signatureFormat))
         throw new Error(`Unsupported signature format: ${signatureFormat}`);
     const toleranceInSeconds = options.toleranceInSeconds;
     if (toleranceInSeconds !== undefined) {
@@ -48,4 +54,9 @@ export default async function hmac(options) {
         .digest();
     return timingSafeCompare(expected, candidate, signatureFormat);
 }
+export default function hmac(options) {
+    return new Promise(resolve => {
+        resolve(verifyHmac(options));
+    });
+}
 //# sourceMappingURL=hmac-authorize.js.map

package/dist/hmac-authorize.js.map

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

package/dist/models/HMACAuthorization.d.ts

@@ -5,7 +5,7 @@ export type HMACAuthorizationContext = {
     signature: string;
     rawPayload: string;
     algorithm?: string;
-    signatureFormat?: BinaryToTextEncoding | string;
+    signatureFormat?: BinaryToTextEncoding | (string & {});
     signaturePrefix?: string;
     timestamp?: string;
     toleranceInSeconds?: number;

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

@@ -1 +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"}
+{"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,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;IACtD,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/hmac",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "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",
@@ -36,12 +36,14 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "check-types": "tsc --noEmit",
+    "check-package": "publint --strict && attw --pack . --profile esm-only",
+    "lint": "eslint . --max-warnings 0",
     "prepublishOnly": "yarn build",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.19.0",
+    "@t4h.framework/core": "^0.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },