@boxxy/caller-proof-imp 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the boxxy authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@boxxy/caller-proof-imp</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <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>
+
+  <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,6 +1,45 @@
 {
   "name": "@boxxy/caller-proof-imp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/boxxy.git",
+    "directory": "adapters/caller-proof-imp"
+  },
+  "files": [
+    "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.3",
+    "@impz/client": "6.12.0"
+  },
+  "devDependencies": {
+    "@boxxy/dispatch": "0.1.3",
+    "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;
+}