@metalabel/dfos-client 0.32.0 → 0.33.0

package/README.md

@@ -1,6 +1,8 @@
 # @metalabel/dfos-client
 
-The high-level read client for the [DFOS protocol](https://protocol.dfos.com). The protocol library owns the crypto truth (CID re-derivation, signature verification, chain folding); this client owns the four things it deliberately refuses to do: **fetch, resolve, verify-orchestration, and cache** — over an untrusted set of relays. It holds no keys and never writes.
+The client-side kit for participating in the [DFOS protocol](https://protocol.dfos.com) — **resolve, verify, prove**. The protocol library owns the crypto truth (CID re-derivation, signature verification, chain folding); this client owns the four things it deliberately refuses to do: **fetch, resolve, verify-orchestration, and cache** — over an untrusted set of relays — plus the two proof surfaces that ride on top of them, [SIWD](#metalabeldfos-clientsiwd) and [API-AUTH](#metalabeldfos-clientapi-auth).
+
+**It holds no keys.** Signing is always a `sign` callback the caller supplies: this kit composes the exact bytes that must be signed and hands them over, and key material never crosses into it.
 
 If verification logic appears in this package, that is the bug: every proof comes from `@metalabel/dfos-protocol`.
 
@@ -73,6 +75,65 @@ import { indexedDbStore, memoryStore } from '@metalabel/dfos-client/store';
 
 `memoryStore()` (the isomorphic default) caches the **log**. Chain reads fully drain from zero, require the fetched JWS tokens to match the trusted cached prefix, and verify forward only the suffix, so a key rotation costs one verification op and the cache is never stale-wrong. `indexedDbStore()` is the browser-only durable adapter — the only heavy dependency, quarantined behind this subpath.
 
+### `@metalabel/dfos-client/api-auth`
+
+API Authentication request proofs. A proof is a short-lived JWS, signed by the key a DFOS credential was issued to, that binds one exact HTTP request — method, host, path, body — to that credential. The credential says what its holder may do; the proof says the holder is the one doing it, and doing exactly this. See the [API-AUTH specification](https://protocol.dfos.com/api-auth).
+
+**Spending a credential: a signing `fetch`.** Hand it to any API client with a fetch seam, and every request that client composes goes out credential-gated.
+
+```typescript
+import { createDfosApi } from '@metalabel/dfos-api';
+import { createApiAuthFetch } from '@metalabel/dfos-client/api-auth';
+
+const api = createDfosApi({ fetch: createApiAuthFetch({ credential, kid, sign }) });
+
+const { data } = await api.GET('/profile');
+```
+
+Three inputs, and they are the irreducible ones: the credential JWS to present, the DID URL of the key it was issued to, and a `sign` callback over bytes. The proof's `credentialCID` is read from the credential's own header, so the two can never drift apart. Pass `fetch` to supply the underlying transport (default `globalThis.fetch`).
+
+It signs **exactly the `Request` it receives** — the method, the origin-form target, and the body octets already composed — rather than a description of one. That is what keeps the binding honest: the bytes the proof covers are the bytes that go on the wire.
+
+Three consequences worth knowing before you wire it up:
+
+- **It refuses to sign a plaintext request** to anything but loopback (`localhost`, `127.0.0.1`, `[::1]`). `api:` surfaces are HTTPS surfaces, and a proof sent in the clear replays for its whole freshness window.
+- **It does not follow redirects** (`redirect: 'manual'`): a 3xx comes back to you as-is, because following it would re-issue the request at coordinates the proof does not cover and carry `X-Credential` to whatever authority the `Location` names.
+- **It buffers the request body before sending.** The proof covers the whole body, so there is nothing to sign until the last octet is in hand — size-bounded requests only. An unbounded or live stream cannot be proof-signed, in any implementation.
+
+**A backend that must not proxy uses the decomposed form.** A signing backend fronting a browser must authorize the coordinates it is about to sign against its own session, not sign whatever `{method, path, body}` the browser hands it — a backend that signs blindly is an oracle for every credential it holds ([Security Considerations](https://protocol.dfos.com/api-auth#security-considerations)). Such a backend describes the one request it is willing to make, so there is no `Request` for the adapter above to cover:
+
+```typescript
+import { buildApiAuthHeaders, signApiRequest } from '@metalabel/dfos-client/api-auth';
+
+const { proof } = await signApiRequest({
+  method: 'GET',
+  host: 'api.example',
+  path: '/profile',
+  credentialCID,
+  kid,
+  sign,
+});
+const headers = buildApiAuthHeaders({ proof, credential });
+```
+
+**Verifying** is the other half, and it lives here so that an API host's middleware is a thin adapter over the kit rather than a second implementation of the spec's eleven steps:
+
+```typescript
+import { verifyApiRequest } from '@metalabel/dfos-client/api-auth';
+
+await verifyApiRequest(client, {
+  proof,
+  credential,
+  method: 'GET',
+  host: 'api.example', // the verifier's OWN configured authority, never a request header
+  path: '/profile',
+});
+```
+
+It throws `ApiRequestVerifyError`, carrying `reason` (`invalid` / `unverifiable` / `config`), `phase`, and the recommended `status` — branch on those, never on message text.
+
+`apiRequestSigningInput(payload)` is the pure byte contract both halves share, and the one place per language the canonical bytes are built.
+
 ### `@metalabel/dfos-client/siwd`
 
 ```typescript

package/dist/api-auth.d.ts

@@ -119,6 +119,59 @@ declare const buildApiAuthHeaders: (input: {
     Authorization: string;
     "X-Credential": string;
 };
+interface CreateApiAuthFetchOptions {
+    /**
+     * The leaf credential JWS to present — the `X-Credential` value, and the
+     * source of every proof's `credentialCID`. It embeds its chain in `prf`.
+     */
+    credential: string;
+    /**
+     * The signing key's DID URL. Its DID portion MUST be the credential's `aud` —
+     * that equality IS the possession being proven.
+     */
+    kid: string;
+    /** Raw Ed25519 signer over the JWS signing input. Never key material. */
+    sign: (message: Uint8Array) => Promise<Uint8Array>;
+    /** The underlying transport. Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * A signing `fetch`. Hand it to any API client with a fetch seam and every
+ * request that client composes goes out credential-gated:
+ *
+ * ```ts
+ * createDfosApi({ fetch: createApiAuthFetch({ credential, kid, sign }) })
+ * ```
+ *
+ * It signs EXACTLY the `Request` it receives — the method, the origin-form
+ * target, and the body octets already composed — rather than a description of
+ * one. That is what keeps the binding honest: the bytes the proof covers are the
+ * bytes that go on the wire.
+ *
+ * `signApiRequest` stays exported for the backends that must NOT proxy. A
+ * signing backend fronting a browser MUST authorize the coordinates it is about
+ * to sign against its own session (API-AUTH.md, Security Considerations) — it
+ * describes the one request it is willing to make rather than receiving one, so
+ * there is no `Request` for this adapter to cover.
+ *
+ * Two things are deliberately absent. There is no credential-provider callback:
+ * a caller whose credential rotates builds a new fetch, which is one line and
+ * has no lifecycle to get wrong. And there is no host allowlist: the caller
+ * composing the URL is already the party choosing the host, so an allowlist here
+ * would guard a decision it does not make.
+ *
+ * TWO REFUSALS, both because the adapter is the last place that can see them.
+ * It will not sign a plaintext request to a real host (`api:` surfaces are HTTPS
+ * surfaces — the proof and the credential would go out in the clear, and the
+ * proof replays over HTTPS for its whole freshness window), and it will not
+ * follow redirects.
+ *
+ * BUFFERING IS INHERENT. The byte contract hashes the complete body before
+ * signing, so a request body is buffered in full before anything is sent. This
+ * adapter is for size-bounded requests; an unbounded or live stream cannot be
+ * proof-signed at all, in any implementation.
+ */
+declare const createApiAuthFetch: (options: CreateApiAuthFetchOptions) => typeof fetch;
 /**
  * The verdict class. Branch on `reason`, never on message text.
  *
@@ -240,4 +293,4 @@ interface VerifiedRequestProof {
  */
 declare const verifyApiRequest: (client: Client, input: VerifyApiRequestInput) => Promise<VerifiedRequestProof>;
 
-export { ApiRequestVerifyError, DEFAULT_API_ACTION, DEFAULT_PROOF_SKEW_SECONDS, DEFAULT_PROOF_WINDOW_SECONDS, EMPTY_BODY_SHA256, MAX_BODY_BYTES, MAX_PROOF_FRESHNESS_SPAN_SECONDS, MAX_REQUEST_PROOF_SIZE, REQUEST_PROOF_JWS_TYP, type RequestProofFailurePhase, type RequestProofFailureReason, type RequestProofPayload, type SignApiRequestInput, type VerifiedRequestProof, type VerifyApiRequestInput, apiRequestSigningInput, buildApiAuthHeaders, sha256BodyHash, signApiRequest, verifyApiRequest };
+export { ApiRequestVerifyError, type CreateApiAuthFetchOptions, DEFAULT_API_ACTION, DEFAULT_PROOF_SKEW_SECONDS, DEFAULT_PROOF_WINDOW_SECONDS, EMPTY_BODY_SHA256, MAX_BODY_BYTES, MAX_PROOF_FRESHNESS_SPAN_SECONDS, MAX_REQUEST_PROOF_SIZE, REQUEST_PROOF_JWS_TYP, type RequestProofFailurePhase, type RequestProofFailureReason, type RequestProofPayload, type SignApiRequestInput, type VerifiedRequestProof, type VerifyApiRequestInput, apiRequestSigningInput, buildApiAuthHeaders, createApiAuthFetch, sha256BodyHash, signApiRequest, verifyApiRequest };

package/dist/api-auth.js

@@ -134,6 +134,54 @@ var buildApiAuthHeaders = (input) => ({
   Authorization: `DFOS ${input.proof}`,
   "X-Credential": input.credential
 });
+var credentialCIDFromHeader = (credential) => {
+  const decoded = decodeJwsUnsafe(credential);
+  if (!decoded) throw new Error("invalid credential: failed to decode the credential JWS");
+  const cid = decoded.header.cid;
+  if (typeof cid !== "string" || cid === "") {
+    throw new Error("invalid credential: the credential JWS carries no cid header");
+  }
+  return cid;
+};
+var LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+var createApiAuthFetch = (options) => {
+  const credentialCID = credentialCIDFromHeader(options.credential);
+  const send = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  return async (input, init) => {
+    const request = init === void 0 && input instanceof Request ? input : new Request(input, init);
+    const url = new URL(request.url);
+    if (url.protocol !== "https:" && !LOOPBACK_HOSTNAMES.has(url.hostname)) {
+      throw new Error(
+        `refusing to sign a ${url.protocol}// request to ${url.host}: api: surfaces are HTTPS surfaces, and a proof sent in the clear replays for its whole freshness window (plaintext is allowed only to localhost, 127.0.0.1, and [::1])`
+      );
+    }
+    const { proof } = await signApiRequest({
+      method: request.method,
+      // `host`, never `hostname`: the authority carries the port when there is
+      // one, and the verifier compares it byte for byte.
+      host: url.host,
+      // Path plus query, byte for byte — no normalization, because the verifier
+      // compares against the request target it actually received. Dropping
+      // `.search` is the classic silent 401.
+      path: url.pathname + url.search,
+      // Hash the CLONE and forward the original: buffering the request's own
+      // stream would leave nothing to send. Buffering at all is inherent — the
+      // proof covers the WHOLE body, so there is nothing to sign until the last
+      // octet is in hand.
+      body: new Uint8Array(await request.clone().arrayBuffer()),
+      credentialCID,
+      kid: options.kid,
+      sign: options.sign
+    });
+    const headers = new Headers(request.headers);
+    for (const [name, value] of Object.entries(
+      buildApiAuthHeaders({ proof, credential: options.credential })
+    )) {
+      headers.set(name, value);
+    }
+    return send(new Request(request, { headers, redirect: "manual" }));
+  };
+};
 var ApiRequestVerifyError = class extends Error {
   reason;
   phase;
@@ -330,6 +378,7 @@ export {
   REQUEST_PROOF_JWS_TYP,
   apiRequestSigningInput,
   buildApiAuthHeaders,
+  createApiAuthFetch,
   sha256BodyHash,
   signApiRequest,
   verifyApiRequest

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "type": "module",
-  "description": "DFOS Client — read-only resolve + verify orchestration over untrusted relays. Fetch, resolve, verify-orchestration, cache; all crypto truth comes from @metalabel/dfos-protocol",
+  "description": "DFOS Client — the client-side kit for participating in the protocol: resolve, verify, prove. Fetch, resolve, verify-orchestration and cache over untrusted relays, plus the SIWD and API-AUTH proof surfaces. Holds no keys; all crypto truth comes from @metalabel/dfos-protocol",
   "license": "MIT",
   "author": "Metalabel <hello@metalabel.com> (https://metalabel.com)",
   "repository": {
@@ -47,15 +47,15 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@metalabel/dfos-protocol": "^0.32.0",
-    "@metalabel/dfos-web-relay": "^0.32.0"
+    "@metalabel/dfos-protocol": "^0.33.0",
+    "@metalabel/dfos-web-relay": "^0.33.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-protocol": "0.32.0",
-    "@metalabel/dfos-web-relay": "0.32.0"
+    "@metalabel/dfos-protocol": "0.33.0",
+    "@metalabel/dfos-web-relay": "0.33.0"
   },
   "scripts": {
     "build": "tsup",