@t4h.framework/hmac 0.3.8 → 0.3.11

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

@@ -1,244 +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` |
+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 {
-  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'
 
-import { environments } from './constants/environments.js'
+import { environments } from '../constants/environments.js'
 
-const authorization = new HMACAuthorization({
+export const authorization = new HMACAuthorization({
   secret: environments.HMAC_SECRET,
-  signature: '<signature-from-runtime>',
-  rawPayload: '<exact-signed-bytes>',
+  signature: '<signature-from-the-request-header>',
+  rawPayload: '<the-exact-request-body>',
   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
-  },
-}
-```
+## Verify async activity callbacks
 
-Optional manifest fields are still present as `undefined` when omitted (`toManifest` copies all keys).
-
-Declare the secret in the `EnvDesign` in `src/constants/environments.ts`. The context types `secret` as `string`, so declare the entry with `type: String`, not `type: Secret`. This is an exception to the `type: Secret` rule of **framework-core**.
-
----
-
-## Context: `HMACAuthorizationContext`
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `secret` | Yes | Shared secret, used as **UTF-8 bytes** for the HMAC key. 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 | `HMACAlgorithm` key: `SHA1`, `SHA256`, `SHA384` or `SHA512` (not `sha256`). Defaults to `SHA256`. Other values throw. |
-| `signatureFormat` | No | Encoding of `signature`: `hex`, `base64`, `base64url` or `binary`. Defaults to `hex`. Other values throw. |
-| `signaturePrefix` | No | Stripped before comparison, e.g. `sha256=`. If set and absent from `signature` → `false`. |
-| `timestamp` | Conditional | Used with `toleranceInSeconds`. 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:
+The `auth` object names request headers, not values. Its `secret` IS a
+`Secret`: declare it with `type: Secret` and pass it whole.
 
 ```typescript
-(options: HMACAuthorizationContext) => Promise<boolean>
-```
-
-Behavior, in order (from `hmac-authorize.ts` and tests):
-
-1. Falsy `signature` → **`false`** (no throw).
-2. Check the configuration (see **Return values vs errors**).
-3. If `toleranceInSeconds` is set: `timestamp` outside the window or unparseable → **`false`**.
-4. If `signaturePrefix` is set and `signature` does not start with it → **`false`**; otherwise strip it.
-5. 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',
-}
-```
-
----
-
-## Examples
-
-### Webhook with a prefixed hex signature (GitHub style)
-
-```typescript
-new HMACAuthorization({
-  secret: environments.HMAC_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: environments.HMAC_SECRET,
-  signature: parsedSignatureHeader.v1,
-  rawPayload: `${timestamp}.${rawRequestBody}`, // timestamp bound INTO the signature
-  timestamp,
+auth: {
+  type: 'hmac',
+  secret: environments.PARTNER_SECRET,
+  header: 'x-slack-signature',
+  signaturePrefix: 'v0=',
+  timestampHeader: 'x-slack-request-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: environments.HMAC_SECRET,
-  signature: base64Signature,
-  rawPayload: canonicalPayloadString,
-  algorithm: 'SHA512',
-  signatureFormat: 'base64',
-})
+  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`, unknown `algorithm` or `signatureFormat`, `toleranceInSeconds` without `timestamp` | **Throw** (`hmac-authorize.ts`) |
-
-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()`.
+For a tolerance test, set the clock with `vi.useFakeTimers()` and
+`vi.setSystemTime(...)`.
 
-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`.
+## Related skills
 
----
+- **framework-jwks**: public-key signatures and JWTs.
+- **framework-webhook**: wait for a partner callback that uses this `auth`.
 
-## 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**.
-
----
+## 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`.
-7. Add `timestamp` + `toleranceInSeconds` for replay protection, and bind the timestamp into `rawPayload`.
-8. `@t4h.framework/core/no-literal-secret-in-authorization` rejects a literal `secret`. Read it from the `EnvDesign` in `src/constants/environments.ts`.
-9. Expect `false` for deny, throws for misconfiguration.
+- 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,19 @@
 # @t4h.framework/hmac
 
+## 0.3.11
+
+### Patch Changes
+
+- [#276](https://github.com/tech4humans-brasil/framework/pull/276) [`7b38934`](https://github.com/tech4humans-brasil/framework/commit/7b38934e8f9207c98c33afcd76e3a7a4da7e8b14) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The install command gives the `@t4h.framework/core` peer, and the samples import `HMACAuthorization`. The docs tell that `./callback` reads the headers and the secret.
+
+## 0.3.10
+
+## 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

package/README.md

@@ -1,61 +1,16 @@
 # @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'
@@ -67,20 +22,13 @@ const authorization = new HMACAuthorization({
   signature: '<signature-from-the-request-header>',
   rawPayload: '<the-exact-request-body>',
   signaturePrefix: 'sha256=',
-  timestamp: '<timestamp-from-the-request-header>',
-  toleranceInSeconds: 300,
 })
 ```
 
-Declare `HMAC_SECRET` in the `EnvDesign` in `src/constants/environments.ts` with `type: String`, because the `secret` field is a string:
-
-```typescript
-// src/constants/environments.ts
-import { EnvDesign } from '@t4h.framework/core'
+Declare `HMAC_SECRET` with `type: String` in the `EnvDesign` in
+`src/constants/environments.ts`, and attach `authorization` to a `Workflow` or
+an `App`.
 
-export const environments = EnvDesign({
-  HMAC_SECRET: { type: String },
-})
-```
+## Documentation
 
-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.
+<https://tech4humans-brasil.github.io/framework/hmac/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/hmac",
-  "version": "0.3.8",
+  "version": "0.3.11",
   "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",
@@ -43,7 +43,7 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.20.0",
+    "@t4h.framework/core": "^0.21.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },