Skip to main content

hawk

@webda/hawk

Hawk HTTP authentication for Webda — HMAC-signed request authentication using API keys stored in a Webda Store, with optional session-bound dynamic keys.

When to use it​

  • You need server-to-server or machine-to-machine authentication via HMAC-signed HTTP requests (the Hawk protocol).
  • You want to manage API keys as first-class Webda models with full CRUD, revocation, and audit trail support.
  • You need an alternative to Bearer tokens that also covers request integrity (method + URL included in the signature).

Install​

pnpm add @webda/hawk

Configuration​

{
  "services": {
    "hawk": {
      "type": "Hawk",
      "keyModel": "MyApp/ApiKey"
    },
    "apiKeyStore": {
      "type": "MemoryStore",
      "model": "MyApp/ApiKey"
    }
  }
}
ParameterTypeDefaultRequiredDescription
keyModelstring—NoFully qualified model name for API key lookup (must extend ApiKey)
dynamicSessionKeystring—NoSession attribute to read a per-session HMAC key from
redirectUrlstring—NoURL to redirect to after successful key exchange
redirectUrisstring[][]NoWhitelist of allowed redirect URIs for CSRF protection

Usage​

// 1. Create an API key for a client
import { ApiKey } from "@webda/hawk";
import { Bean, Inject } from "@webda/core";
import HawkService from "@webda/hawk";

@Bean
export class ApiKeyManager extends Service {
  @Inject("hawk")
  hawk: HawkService;

  async issueKey(clientId: string): Promise<ApiKey> {
    const key = new ApiKey();
    key.clientId = clientId;
    // key.key and key.algorithm are auto-generated
    return key.save();
  }
}

// 2. Sign a request on the client side (e.g. using the hawk npm package)
import * as Hawk from "hawk";

const { header } = Hawk.client.header(
  "https://api.example.com/orders",
  "GET",
  { credentials: { id: apiKeyId, key: apiKeySecret, algorithm: "sha256" } }
);
// Send the Authorization: Hawk ... header

// 3. HawkService automatically validates incoming requests as a RequestFilter
// before other route handlers run — no additional middleware needed.

Reference​

  • API reference: see the auto-generated typedoc at docs/pages/Modules/hawk/.
  • Source: packages/hawk
  • Related: @webda/core for RequestFilter; @webda/async for pairing Hawk-authenticated job callbacks.

Classes​

Interfaces​