@boxxy/caller-proof-imp 0.0.1 → 0.1.4

package/README.md

@@ -1,7 +1,42 @@
-# @boxxy/caller-proof-imp
+<div align="center">
+  <h1>@boxxy/caller-proof-imp</h1>
 
-This version, 0.0.1, is a placeholder. It holds no code. It reserves the name on npm so that the
-boxxy release can publish every real version from CI with provenance.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/caller-proof-imp"><img src="https://img.shields.io/npm/v/@boxxy/caller-proof-imp" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
 
-Install a version above 0.0.1. The source lives in [`adapters/caller-proof-imp`](https://github.com/zgeoff/boxxy/tree/main/adapters/caller-proof-imp)
-of the [boxxy repo](https://github.com/zgeoff/boxxy).
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+boxxy's `CallerProof` port on the imp broker's identity token: it proves which machine sent a
+session's call to the boxxy server.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/caller-proof-imp) with Bun:
+
+```bash
+bun add @boxxy/caller-proof-imp
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `impIdentityCallerProof({ issuers, audience, clock })` returns a `CallerProof`. The app passes the
+  trust documents as parsed JSON, the audience that the broker signs for, and the clock.
+- The proof reads the `imp-identity` header and verifies it with `@impz/client/identity`. It gives
+  the token's issuer, and the machine ID as the subject.
+- A missing, expired or forged token, a wrong audience or an unknown issuer proves no caller. With
+  no trust document, the proof proves no request.
+- A bad trust document throws when the app builds the proof, so the server does not start.
+- `./test-utils/create-test-issuer`, an issuer with a key made at run time that signs tokens as the
+  broker does, for tests.
+
+## Documentation
+
+[The proven caller](../../docs/design/boxxy/v1-api-and-auth.md#the-proven-caller) describes how the
+server uses the proof, and why the adapter makes no session check of its own.

package/dist/imp-identity-caller-proof.d.ts

@@ -0,0 +1,3 @@
+import type { CallerProof } from '@boxxy/model';
+import type { ImpIdentityCallerProofOptions } from './types.ts';
+export declare function impIdentityCallerProof(options: ImpIdentityCallerProofOptions): CallerProof;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { impIdentityCallerProof } from './imp-identity-caller-proof.ts';
+export type { ImpIdentityCallerProofOptions } from './types.ts';

package/dist/test-utils/create-test-issuer.d.ts

@@ -0,0 +1,13 @@
+interface TestTokenClaims {
+    readonly sub: string;
+    readonly aud: string;
+    readonly iat: number;
+    readonly exp: number;
+    readonly impName: string;
+}
+export interface TestIssuer {
+    readonly document: unknown;
+    readonly signToken: (claims: TestTokenClaims) => Promise<string>;
+}
+export declare function createTestIssuer(issuer: string): Promise<TestIssuer>;
+export {};

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+import type { Clock } from '@boxxy/model';
+export interface ImpIdentityCallerProofOptions {
+    readonly issuers: readonly unknown[];
+    readonly audience: string;
+    readonly clock: Clock;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boxxy/caller-proof-imp",
-  "version": "0.0.1",
-  "description": "Placeholder that reserves the name; the first real version comes from the boxxy release",
+  "version": "0.1.4",
+  "description": "boxxy's caller proof port on the broker's identity token",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/adapters/caller-proof-imp#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
   "license": "MIT",
@@ -11,10 +11,35 @@
     "directory": "adapters/caller-proof-imp"
   },
   "files": [
-    "README.md",
-    "LICENSE"
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
   ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./test-utils/*": "./src/test-utils/*.ts"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "@boxxy/model": "0.1.4",
+    "@impz/client": "6.12.0"
+  },
+  "devDependencies": {
+    "@boxxy/dispatch": "0.1.4",
+    "tiny-invariant": "1.3.3"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
   }
 }

package/src/imp-identity-caller-proof.ts

@@ -0,0 +1,31 @@
+import type { CallerProof, Clock } from '@boxxy/model';
+import { loadIdentityIssuers, verifyImpIdentity } from '@impz/client/identity';
+import type { ImpIdentityCallerProofOptions } from './types.ts';
+
+const identityHeader = 'imp-identity';
+
+// The proof from the broker's identity token. The trust documents are checked once, here, so a
+// bad document stops the server at start. With no document, the proof proves no request.
+export function impIdentityCallerProof(options: ImpIdentityCallerProofOptions): CallerProof {
+  if (options.issuers.length === 0 || options.audience === '') {
+    return { prove: () => Promise.resolve(null) };
+  }
+
+  const issuers = loadIdentityIssuers(options.issuers);
+
+  return {
+    prove: async (request) => {
+      const verified = await verifyImpIdentity(request.headers.get(identityHeader), {
+        issuers,
+        audience: options.audience,
+        nowSeconds: toNowSeconds(options.clock),
+      });
+
+      return verified === null ? null : { issuer: verified.issuer, subject: verified.id };
+    },
+  };
+}
+
+function toNowSeconds(clock: Clock): number {
+  return Math.floor(clock.now() / 1000);
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { impIdentityCallerProof } from './imp-identity-caller-proof.ts';
+export type { ImpIdentityCallerProofOptions } from './types.ts';

package/src/test-utils/create-test-issuer.ts

@@ -0,0 +1,64 @@
+interface TestTokenClaims {
+  readonly sub: string;
+  readonly aud: string;
+  readonly iat: number;
+  readonly exp: number;
+  readonly impName: string;
+}
+
+export interface TestIssuer {
+  // the trust document of the issuer, as the deployment's file holds it
+  readonly document: unknown;
+  readonly signToken: (claims: TestTokenClaims) => Promise<string>;
+}
+
+// An issuer with a key pair made at run time, which signs identity tokens as the broker does: a
+// compact ES256 JWT whose signature is the raw 64-byte r and s.
+export async function createTestIssuer(issuer: string): Promise<TestIssuer> {
+  const kid = `${issuer}-key-1`;
+
+  const keys = await crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, [
+    'sign',
+    'verify',
+  ]);
+
+  const publicKey = await crypto.subtle.exportKey('jwk', keys.publicKey);
+
+  return {
+    document: {
+      issuer,
+      keys: [
+        { kty: 'EC', crv: 'P-256', x: publicKey.x, y: publicKey.y, kid, alg: 'ES256', use: 'sig' },
+      ],
+      retire: [],
+    },
+    signToken: async (claims) => {
+      const header = toBase64URL(JSON.stringify({ alg: 'ES256', kid, typ: 'JWT' }));
+
+      const payload = toBase64URL(
+        JSON.stringify({
+          iss: issuer,
+          sub: claims.sub,
+          aud: claims.aud,
+          iat: claims.iat,
+          exp: claims.exp,
+          imp_name: claims.impName,
+        }),
+      );
+
+      const signature = await crypto.subtle.sign(
+        { name: 'ECDSA', hash: 'SHA-256' },
+        keys.privateKey,
+        new TextEncoder().encode(`${header}.${payload}`),
+      );
+
+      return `${header}.${payload}.${toBase64URL(new Uint8Array(signature))}`;
+    },
+  };
+}
+
+function toBase64URL(content: string | Uint8Array): string {
+  const bytes = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+
+  return Buffer.from(bytes).toString('base64url');
+}

package/src/types.ts

@@ -0,0 +1,10 @@
+import type { Clock } from '@boxxy/model';
+
+export interface ImpIdentityCallerProofOptions {
+  // the trust documents as parsed JSON, one per issuer; the app reads the files
+  readonly issuers: readonly unknown[];
+
+  // the made-up host that the sessions call, which the broker names as the token's audience
+  readonly audience: string;
+  readonly clock: Clock;
+}