@mutmutco/installer-gate 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# @mutmutco/installer-gate
+
+A small, framework-agnostic **node:http** server library a product mounts to run its *installer
+gate*: it drives the GitHub device flow (or verifies a Google bearer), enforces an allowlist, and
+serves an Ed25519-signed release manifest plus the release files it describes.
+
+- Node **>= 22**, **ESM**, **zero runtime dependencies** (node: builtins only).
+- The library never hardcodes a credential: the GitHub client id/secret and every product-specific
+  piece (manifest, signer, file reader, bearer verifier) are **injected** by the adopter.
+- The published package ships a built ESM bundle (`dist/index.js`) plus declarations (`dist/*.d.ts`);
+  `npm run build` produces both — esbuild bundles the entry and `tsc -p tsconfig.build.json` emits
+  types only. The adopter imports `@mutmutco/installer-gate` directly; no bundler step is required.
+
+## Mounting
+
+```ts
+import http from 'node:http';
+import { sign as cryptoSign } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createGateHandler } from '@mutmutco/installer-gate';
+
+const gate = createGateHandler({
+  kind: 'github',
+  githubClientId: process.env.GITHUB_CLIENT_ID!,
+  githubClientSecret: process.env.GITHUB_CLIENT_SECRET!,
+  allowlist: { source: 'roster', getLogins: async () => rosterLogins() },
+  release: {
+    manifest: async () => ({
+      version: currentVersion(),
+      files: releaseFiles(), // [{ path, sha256, size }]
+    }),
+    sign: (canonicalBytes) => cryptoSign(null, canonicalBytes, privateKey), // Ed25519, detached
+    readFile: async (path) => readFile(join(releaseRoot, path)),
+  },
+});
+
+http.createServer((req, res) => {
+  if (!gate(req, res)) myOwnRouter(req, res); // false = not a /gate or /release path
+}).listen(8787);
+```
+
+`createGateHandler(config)` returns `(req, res) => boolean`. It owns **`/gate/*`** and
+**`/release/*`**; for those it handles the request and returns `true`. For every other path it
+returns `false` and touches nothing, so the adopter's router continues.
+
+## Config reference
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `kind` | `'github' \| 'google'` | Selects the identity lane. |
+| `githubClientId` | `string` | github kind. The gate rejects a device-flow `client_id` that does not match it. |
+| `githubClientSecret` | `string` | github kind. Passed in by the adopter — **never committed here**. |
+| `githubApiBase` | `string?` | github kind. Default `https://github.com`; override in tests. |
+| `verifyBearer` | `(token) => Promise<{sub}\|null>` | google kind. The product's own OAuth server. |
+| `allowlist` | `{ source: 'roster' \| 'logins', getLogins?: () => Promise<string[]> }` | Allowed identities. |
+| `release` | `{ manifest, sign, readFile }` | How release artifacts are described, signed and read. |
+| `tokenTtlSeconds` | `number?` | Default **3600**; values above 3600 are clamped to 3600. |
+| `revoke` | `string[] \| (() => Promise<string[]>)?` | Explicit revocations, re-read every call. |
+| `tokenSecret` | `string?` | HMAC key for the gate's own tokens. github derives one from the client secret; google mints no tokens. |
+| `now` | `() => number?` | Injectable clock (epoch ms) for tests. |
+
+`release.manifest()` returns `{ version, files: [{ path, sha256, size }] }`. The gate stamps
+`created` (ISO 8601) and signs; `release.readFile(path)` throws when a file is absent.
+
+## Wire contract v1
+
+| Method | Path | Body / headers | Response |
+| --- | --- | --- | --- |
+| POST | `/gate/device/code` | `{ client_id }` | `200 { device_code, user_code, verification_uri, verification_uri_complete?, expires_in, interval }` |
+| POST | `/gate/device/token` | `{ client_id, device_code }` | `200 { access_token, refresh_token, expires_in }` or `400 { error }` |
+| POST | `/gate/refresh` | `{ refresh_token }` | `200 { access_token, expires_in }` or `403 { error }` |
+| GET | `/release/manifest` | `Authorization: Bearer <access_token>` | `200 { version, created, files, signature }` |
+| GET | `/release/<path>` | `Authorization: Bearer <access_token>` | raw bytes, or `404 { error }` |
+
+Device-flow `400` errors are exactly `authorization_pending`, `slow_down`, `expired_token`,
+`denied` (GitHub's `access_denied` maps to `denied`; any other GitHub error is terminal → `denied`).
+
+Refusals: **`401 { error: "unauthorized" }`** for a missing/invalid/expired bearer;
+**`403 { error: "forbidden" }`** for an allowlist miss or a revoked identity.
+
+## Token format
+
+The gate mints its own opaque bearer credentials after the identity is proven:
+
+```
+<base64url(JSON payload)> . <base64url(HMAC-SHA256(payloadB64, tokenSecret))>
+payload = { sub, exp, jti, typ }
+```
+
+`sub` is the identity (GitHub login or Google `sub`), `exp` is epoch seconds, `jti` a random id,
+and `typ` is `'access'` or `'refresh'`. **HMAC-SHA256 is the chosen scheme**: the token only ever
+travels back to the gate that minted it, so a symmetric MAC is sufficient and needs no keypair.
+Tokens are opaque to the client; `mintToken`/`verifyToken` are exported for adopters that need to
+inspect one. `expires_in` is always `<= 3600`.
+
+## Allowlists
+
+- `'logins'` — an explicit list served by `getLogins()`.
+- `'roster'` — the **same interface**; the adopter wires a roster adapter later. The gate treats
+  both sources identically.
+- Matching is case-insensitive and trims whitespace (GitHub logins are case-insensitive).
+- **Fail closed**: a missing `getLogins`, an empty list, or a throw allows nobody.
+- The allowlist is checked **at token mint and on every gated read**, and `revoke` (a list or a
+  function) is re-read on every call — so an allowlist edit or a revocation refuses the very next
+  refresh and release read. Refresh mints a new access token only if the identity still passes.
+
+## Release signing
+
+`GET /release/manifest` returns a **base64 detached Ed25519 signature** over exactly the UTF-8
+bytes of the canonical JSON:
+
+```
+{"created":<created>,"files":[{"path":<path>,"sha256":<sha256>,"size":<size>}],"version":<version>}
+```
+
+Keys sorted lexicographically, arrays in given order, no whitespace. The launcher side verifies
+with the exported helpers:
+
+```ts
+import { verifySignedManifest, verifyReleaseFile } from '@mutmutco/installer-gate';
+
+verifySignedManifest(manifest, publicKey);          // signature over the canonical bytes
+verifyReleaseFile(manifest.files[i], fileBytes);    // size + SHA-256 of a downloaded file
+```
+
+`buildCanonicalManifest(manifest)` returns the exact bytes if you need them; `canonicalJson(value)`
+is the underlying serializer. `GET /release/<path>` refuses any path that escapes the release root
+(`..`, empty/`.` segments, backslashes, absolute paths) with `404 { error: "not_found" }`.
+
+## The google kind
+
+`kind: 'google'` does **not** implement OAuth. `verifyBearer(token)` is the product's own OAuth
+server; the library verifies the returned `sub` against the allowlist on every gated read. There is
+no device flow and no gate-issued refresh token for this kind, so `/gate/device/*` returns
+`404 { error: "not_found" }`.
+
+## Contract-compliance notes (decisions taken)
+
+- **Allowlist miss at token mint** is `403 { error: "forbidden" }`, matching the contract's global
+  refusal rule; the device-token `400` set is reserved for GitHub's poll errors.
+- **`created`** is an ISO 8601 UTC string (`new Date(now).toISOString()`), so it is JSON-quoted in
+  the canonical form.
+- **Token secret** is an added config field. github derives it from `githubClientSecret` when
+  absent; google (which mints nothing) generates an ephemeral one.
+- **`/release/<path>` traversal** is refused rather than delegated to the adopter's `readFile`.
+- **No secrets are committed**; the client secret and signer key are injected at mount time.

package/dist/allowlist.d.ts

@@ -0,0 +1,17 @@
+import type { AllowlistConfig } from './types.js';
+/**
+ * Allowlist resolution.
+ *
+ * Both sources (`'logins'` and `'roster'`) share one interface: `getLogins()` returns the allowed
+ * identities. The gate treats them identically — `'roster'` is the name an adopter uses when a
+ * roster adapter is wired in later, and nothing in the gate changes. Matching is case-insensitive
+ * (GitHub logins are case-insensitive) and trims surrounding whitespace. A missing `getLogins`,
+ * an empty list, or a throw fails CLOSED: the identity is refused.
+ */
+type RevokeSource = string[] | (() => Promise<string[]>) | undefined;
+/**
+ * True only when `identity` is on the allowlist and not on the revoke list. Re-reads both sources
+ * on every call, so an allowlist edit or a revocation takes effect on the very next request.
+ */
+export declare function isIdentityAllowed(allowlist: AllowlistConfig, revoke: RevokeSource, identity: string): Promise<boolean>;
+export {};

package/dist/canonical.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical JSON — the byte contract the manifest signature covers.
+ *
+ * Rules (wire contract v1): object keys sorted lexicographically (UTF-16 code-unit order, which
+ * matches byte order for ASCII keys), arrays kept in the given order, `undefined` object members
+ * dropped, and no whitespace anywhere. This is intentionally NOT RFC 8785/JCS (no number
+ * canonicalization, no Unicode escaping rules) — it is exactly the shape the launcher team signs
+ * against, and every producer and verifier here funnels through this one function.
+ */
+export declare function canonicalJson(value: unknown): string;

package/dist/github.d.ts

@@ -0,0 +1,31 @@
+/**
+ * GitHub device flow (OAuth 2.0 Device Authorization Grant) client, plus the identity lookup.
+ *
+ * Everything talks to `githubApiBase` (default `https://github.com`), which tests point at a local
+ * fake server so no real network is touched. The gate never hardcodes credentials: the client id
+ * and secret arrive in config.
+ */
+export interface GitHubDeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval: number;
+}
+export type GitHubDeviceTokenResult = {
+    access_token: string;
+} | {
+    error: string;
+};
+/** The four poll errors the wire contract exposes. */
+export type GateDeviceError = 'authorization_pending' | 'slow_down' | 'expired_token' | 'denied';
+export declare function normalizeGitHubApiBase(base?: string): string;
+/** Starts a device authorization. `POST /gate/device/code` proxies this. */
+export declare function requestDeviceCode(apiBase: string, clientId: string): Promise<GitHubDeviceCodeResponse>;
+/** Exchanges a device code for a GitHub access token. Returns the raw result, error included. */
+export declare function pollDeviceToken(apiBase: string, clientId: string, clientSecret: string, deviceCode: string): Promise<GitHubDeviceTokenResult>;
+/** Maps a GitHub poll error onto the wire contract's four-value error set. */
+export declare function mapDeviceError(error: string): GateDeviceError;
+/** Resolves the authenticated GitHub login for a token. */
+export declare function fetchGitHubLogin(apiBase: string, accessToken: string): Promise<string>;

package/dist/google.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Google gate identity resolution.
+ *
+ * The gate does NOT implement OAuth: bearer verification is the product's own OAuth server,
+ * injected as `verifyBearer`. This module only names the contract and wraps the call so a throw
+ * fails closed as "unauthorized" rather than crashing the request.
+ */
+export type BearerVerifier = (token: string) => Promise<{
+    sub: string;
+} | null>;
+/**
+ * Runs the injected verifier. Returns the identity `sub`, or null when the token is invalid, the
+ * verifier returns nothing usable, or the verifier throws.
+ */
+export declare function resolveGoogleIdentity(verifyBearer: BearerVerifier, token: string): Promise<string | null>;

package/dist/handler.d.ts

@@ -0,0 +1,9 @@
+import type { GateConfig, GateHandler } from './types.js';
+/** Rejects any path that could escape the release root. Returns the normalized relative path. */
+export declare function safeReleasePath(rawPath: string): string | null;
+/**
+ * Builds the mountable gate handler. The returned function owns `/gate/*` and `/release/*`:
+ * it handles them and returns `true`; every other path returns `false` so the product's own
+ * router keeps going. Errors never escape — an unexpected failure becomes a 500 JSON body.
+ */
+export declare function createGateHandler(config: GateConfig): GateHandler;

package/dist/http.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Small node:http helpers — no framework, no dependencies. */
+/** Request path without query string. */
+export declare function requestPath(req: IncomingMessage): string;
+/** HTTP error carrying a status and the JSON `error` code the wire contract uses. */
+export declare class GateHttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string);
+}
+/** Reads and parses a JSON request body. Empty body parses to `{}`. */
+export declare function readJsonBody(req: IncomingMessage): Promise<Record<string, unknown>>;
+/** Returns the bearer token from the Authorization header, or null. */
+export declare function bearerToken(req: IncomingMessage): string | null;
+export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
+export declare function sendBytes(res: ServerResponse, status: number, bytes: Buffer): void;
+/** Reads a string field from a parsed body, or undefined when absent/not a string. */
+export declare function stringField(body: Record<string, unknown>, key: string): string | undefined;

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @mutmutco/installer-gate — a small node:http server library a product mounts to run its
+ * installer gate: GitHub device flow (or Google bearer verification), allowlisted identities,
+ * and Ed25519-signed release reads.
+ *
+ * Zero runtime dependencies (node: builtins only). Node >= 22, ESM.
+ *
+ *   import { createGateHandler } from '@mutmutco/installer-gate';
+ *   const gate = createGateHandler(config);
+ *   http.createServer((req, res) => { if (!gate(req, res)) myRouter(req, res); }).listen(8787);
+ */
+export { createGateHandler, safeReleasePath } from './handler.js';
+export { buildCanonicalManifest, sha256Hex, signManifest, verifyManifestSignature, verifyReleaseFile, verifySignedManifest, } from './release.js';
+export { canonicalJson } from './canonical.js';
+export { isIdentityAllowed } from './allowlist.js';
+export { mintToken, verifyToken } from './tokens.js';
+export type { GateTokenPayload } from './tokens.js';
+export { fetchGitHubLogin, mapDeviceError, normalizeGitHubApiBase, pollDeviceToken, requestDeviceCode, } from './github.js';
+export type { GateDeviceError, GitHubDeviceCodeResponse, GitHubDeviceTokenResult, } from './github.js';
+export { resolveGoogleIdentity } from './google.js';
+export type { BearerVerifier } from './google.js';
+export type { AllowlistConfig, GateConfig, GateHandler, GitHubGateConfig, GoogleGateConfig, ReleaseConfig, ReleaseFileEntry, ReleaseManifestInput, SignedReleaseManifest, } from './types.js';

package/dist/index.js

@@ -0,0 +1,532 @@
+// src/handler.ts
+import { randomBytes } from "node:crypto";
+
+// src/allowlist.ts
+function normalize(identity) {
+  return identity.trim().toLowerCase();
+}
+async function readList(source) {
+  if (source === void 0) return [];
+  try {
+    const value = typeof source === "function" ? await source() : source;
+    return Array.isArray(value) ? value : [];
+  } catch {
+    return [];
+  }
+}
+async function isIdentityAllowed(allowlist, revoke, identity) {
+  const normalized = normalize(identity);
+  if (normalized.length === 0) return false;
+  const revoked = new Set((await readList(revoke)).map(normalize));
+  if (revoked.has(normalized)) return false;
+  const allowed = new Set((await readList(allowlist.getLogins)).map(normalize));
+  return allowed.has(normalized);
+}
+
+// src/github.ts
+function normalizeGitHubApiBase(base) {
+  return (base ?? "https://github.com").replace(/\/+$/, "");
+}
+async function formPost(url, params) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "content-type": "application/x-www-form-urlencoded",
+      "user-agent": "mmi-installer-gate"
+    },
+    body: new URLSearchParams(params).toString()
+  });
+  if (!response.ok) {
+    throw new Error(`github ${url} responded ${response.status}`);
+  }
+  const data = await response.json();
+  if (typeof data !== "object" || data === null) throw new Error("github returned a non-object body");
+  return data;
+}
+async function requestDeviceCode(apiBase, clientId) {
+  const data = await formPost(`${apiBase}/login/device/code`, { client_id: clientId });
+  const deviceCode = data.device_code;
+  const userCode = data.user_code;
+  const verificationUri = data.verification_uri;
+  const expiresIn = data.expires_in;
+  const interval = data.interval;
+  if (typeof deviceCode !== "string" || typeof userCode !== "string" || typeof verificationUri !== "string" || typeof expiresIn !== "number" || typeof interval !== "number") {
+    throw new Error("github device code response is missing required fields");
+  }
+  const result = {
+    device_code: deviceCode,
+    user_code: userCode,
+    verification_uri: verificationUri,
+    expires_in: expiresIn,
+    interval
+  };
+  if (typeof data.verification_uri_complete === "string") {
+    result.verification_uri_complete = data.verification_uri_complete;
+  }
+  return result;
+}
+async function pollDeviceToken(apiBase, clientId, clientSecret, deviceCode) {
+  const data = await formPost(`${apiBase}/login/oauth/access_token`, {
+    client_id: clientId,
+    client_secret: clientSecret,
+    device_code: deviceCode,
+    grant_type: "urn:ietf:params:oauth:grant-type:device_code"
+  });
+  if (typeof data.access_token === "string" && data.access_token.length > 0) {
+    return { access_token: data.access_token };
+  }
+  const error = typeof data.error === "string" ? data.error : "unknown_error";
+  return { error };
+}
+function mapDeviceError(error) {
+  switch (error) {
+    case "authorization_pending":
+      return "authorization_pending";
+    case "slow_down":
+      return "slow_down";
+    case "expired_token":
+      return "expired_token";
+    // GitHub's `access_denied` is the user declining; every other code is terminal too.
+    default:
+      return "denied";
+  }
+}
+async function fetchGitHubLogin(apiBase, accessToken) {
+  const response = await fetch(`${apiBase}/user`, {
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `Bearer ${accessToken}`,
+      "user-agent": "mmi-installer-gate"
+    }
+  });
+  if (!response.ok) throw new Error(`github /user responded ${response.status}`);
+  const data = await response.json();
+  const login = data?.login;
+  if (typeof login !== "string" || login.length === 0) {
+    throw new Error("github /user response has no login");
+  }
+  return login;
+}
+
+// src/google.ts
+async function resolveGoogleIdentity(verifyBearer, token) {
+  try {
+    const identity = await verifyBearer(token);
+    if (identity && typeof identity.sub === "string" && identity.sub.length > 0) {
+      return identity.sub;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/http.ts
+function requestPath(req) {
+  const raw = req.url ?? "/";
+  const query = raw.indexOf("?");
+  return query === -1 ? raw : raw.slice(0, query);
+}
+var GateHttpError = class extends Error {
+  constructor(status, code) {
+    super(`${status} ${code}`);
+    this.status = status;
+    this.code = code;
+    this.name = "GateHttpError";
+  }
+  status;
+  code;
+};
+var MAX_BODY_BYTES = 64 * 1024;
+async function readJsonBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > MAX_BODY_BYTES) throw new GateHttpError(413, "payload_too_large");
+    chunks.push(buffer);
+  }
+  if (size === 0) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw new GateHttpError(400, "invalid_json");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new GateHttpError(400, "invalid_json");
+  }
+  return parsed;
+}
+function bearerToken(req) {
+  const header = req.headers.authorization;
+  if (typeof header !== "string") return null;
+  const match = /^Bearer\s+(\S+)$/i.exec(header.trim());
+  return match ? match[1] : null;
+}
+function sendJson(res, status, body) {
+  const payload = Buffer.from(JSON.stringify(body), "utf8");
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": String(payload.length),
+    "cache-control": "no-store"
+  });
+  res.end(payload);
+}
+function sendBytes(res, status, bytes) {
+  res.writeHead(status, {
+    "content-type": "application/octet-stream",
+    "content-length": String(bytes.length),
+    "cache-control": "no-store"
+  });
+  res.end(bytes);
+}
+function stringField(body, key) {
+  const value = body[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
+// src/release.ts
+import { createHash, verify } from "node:crypto";
+
+// src/canonical.ts
+function canonicalJson(value) {
+  return encode(value);
+}
+function encode(value) {
+  if (value === null) return "null";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("canonicalJson: cannot encode a non-finite number");
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => encode(entry)).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const record = value;
+    const keys = Object.keys(record).filter((key) => record[key] !== void 0).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${encode(record[key])}`).join(",")}}`;
+  }
+  throw new TypeError(`canonicalJson: cannot encode a value of type ${typeof value}`);
+}
+
+// src/release.ts
+function canonicalManifestObject(manifest) {
+  return {
+    created: manifest.created,
+    files: manifest.files.map((file) => ({
+      path: file.path,
+      sha256: file.sha256,
+      size: file.size
+    })),
+    version: manifest.version
+  };
+}
+function buildCanonicalManifest(manifest) {
+  return Buffer.from(canonicalJson(canonicalManifestObject(manifest)), "utf8");
+}
+function sha256Hex(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function signManifest(manifest, sign2) {
+  return sign2(buildCanonicalManifest(manifest)).toString("base64");
+}
+function verifyManifestSignature(manifest, signature, publicKey) {
+  try {
+    const signatureBytes = Buffer.from(signature, "base64");
+    if (signatureBytes.length === 0) return false;
+    return verify(null, buildCanonicalManifest(manifest), publicKey, signatureBytes);
+  } catch {
+    return false;
+  }
+}
+function verifyReleaseFile(entry, bytes) {
+  return entry.size === bytes.length && sha256Hex(bytes) === entry.sha256;
+}
+function verifySignedManifest(manifest, publicKey) {
+  return verifyManifestSignature(manifest, manifest.signature, publicKey);
+}
+
+// src/tokens.ts
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+function mintToken(secret, identity, typ, expiresInSeconds, nowMs) {
+  const payload = {
+    sub: identity,
+    exp: Math.floor(nowMs / 1e3) + Math.max(1, Math.floor(expiresInSeconds)),
+    jti: randomUUID(),
+    typ
+  };
+  const body = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+  return `${body}.${sign(secret, body)}`;
+}
+function sign(secret, body) {
+  return createHmac("sha256", secret).update(body).digest().toString("base64url");
+}
+function verifyToken(secret, token) {
+  const dot = token.indexOf(".");
+  if (dot <= 0 || dot === token.length - 1) return null;
+  const body = token.slice(0, dot);
+  const provided = token.slice(dot + 1);
+  const expected = sign(secret, body);
+  if (provided.length !== expected.length) return null;
+  if (!timingSafeEqual(Buffer.from(provided), Buffer.from(expected))) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const payload = parsed;
+    if (typeof payload.sub !== "string" || payload.sub.length === 0) return null;
+    if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) return null;
+    if (typeof payload.jti !== "string" || payload.jti.length === 0) return null;
+    if (payload.typ !== "access" && payload.typ !== "refresh") return null;
+    return { sub: payload.sub, exp: payload.exp, jti: payload.jti, typ: payload.typ };
+  } catch {
+    return null;
+  }
+}
+
+// src/handler.ts
+var DEFAULT_TTL_SECONDS = 3600;
+var MAX_TTL_SECONDS = 3600;
+function resolveTtl(config) {
+  const requested = config.tokenTtlSeconds ?? DEFAULT_TTL_SECONDS;
+  if (!Number.isFinite(requested) || requested <= 0) return DEFAULT_TTL_SECONDS;
+  return Math.min(Math.floor(requested), MAX_TTL_SECONDS);
+}
+function resolveSecret(config) {
+  if (config.tokenSecret) return config.tokenSecret;
+  if (config.kind === "github") {
+    return `installer-gate:github:${config.githubClientId}:${config.githubClientSecret}`;
+  }
+  return randomBytes(32).toString("base64url");
+}
+function safeReleasePath(rawPath) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(rawPath);
+  } catch {
+    return null;
+  }
+  if (decoded.length === 0 || decoded.includes("\0") || decoded.includes("\\")) return null;
+  const segments = decoded.split("/");
+  for (const segment of segments) {
+    if (segment === "" || segment === "." || segment === "..") return null;
+  }
+  return segments.join("/");
+}
+function createGateHandler(config) {
+  const now = config.now ?? (() => Date.now());
+  const ttlSeconds = resolveTtl(config);
+  const secret = resolveSecret(config);
+  const githubApiBase = config.kind === "github" ? normalizeGitHubApiBase(config.githubApiBase) : "";
+  return function gateHandler(req, res) {
+    const pathname = requestPath(req);
+    if (!pathname.startsWith("/gate/") && !pathname.startsWith("/release/")) {
+      return false;
+    }
+    void route(req, res, pathname).catch((error) => {
+      if (res.headersSent) {
+        res.end();
+        return;
+      }
+      if (error instanceof GateHttpError) {
+        sendJson(res, error.status, { error: error.code });
+      } else {
+        sendJson(res, 500, { error: "internal_error" });
+      }
+    });
+    return true;
+  };
+  async function route(req, res, pathname) {
+    const method = (req.method ?? "GET").toUpperCase();
+    if (pathname === "/gate/device/code") {
+      requireMethod(method, "POST");
+      if (config.kind !== "github") throw new GateHttpError(404, "not_found");
+      await deviceCode(req, res);
+      return;
+    }
+    if (pathname === "/gate/device/token") {
+      requireMethod(method, "POST");
+      if (config.kind !== "github") throw new GateHttpError(404, "not_found");
+      await deviceToken(req, res);
+      return;
+    }
+    if (pathname === "/gate/refresh") {
+      requireMethod(method, "POST");
+      await refresh(req, res);
+      return;
+    }
+    if (pathname === "/release/manifest") {
+      requireMethod(method, "GET");
+      await releaseManifest(req, res);
+      return;
+    }
+    if (pathname.startsWith("/release/")) {
+      requireMethod(method, "GET");
+      await releaseFile(req, res, pathname.slice("/release/".length));
+      return;
+    }
+    throw new GateHttpError(404, "not_found");
+  }
+  function requireMethod(actual, expected) {
+    if (actual !== expected) throw new GateHttpError(405, "method_not_allowed");
+  }
+  function requireClientId(body) {
+    if (config.kind !== "github") throw new GateHttpError(404, "not_found");
+    const clientId = stringField(body, "client_id");
+    if (!clientId) throw new GateHttpError(400, "invalid_request");
+    if (clientId !== config.githubClientId) throw new GateHttpError(400, "invalid_client");
+    return clientId;
+  }
+  async function deviceCode(req, res) {
+    if (config.kind !== "github") throw new GateHttpError(404, "not_found");
+    const body = await readJsonBody(req);
+    requireClientId(body);
+    let issued;
+    try {
+      issued = await requestDeviceCode(githubApiBase, config.githubClientId);
+    } catch {
+      throw new GateHttpError(502, "upstream_error");
+    }
+    sendJson(res, 200, issued);
+  }
+  async function deviceToken(req, res) {
+    if (config.kind !== "github") throw new GateHttpError(404, "not_found");
+    const body = await readJsonBody(req);
+    requireClientId(body);
+    const deviceCodeValue = stringField(body, "device_code");
+    if (!deviceCodeValue) throw new GateHttpError(400, "invalid_request");
+    let result;
+    try {
+      result = await pollDeviceToken(
+        githubApiBase,
+        config.githubClientId,
+        config.githubClientSecret,
+        deviceCodeValue
+      );
+    } catch {
+      throw new GateHttpError(502, "upstream_error");
+    }
+    if ("error" in result) {
+      sendJson(res, 400, { error: mapDeviceError(result.error) });
+      return;
+    }
+    let identity;
+    try {
+      identity = await fetchGitHubLogin(githubApiBase, result.access_token);
+    } catch {
+      throw new GateHttpError(502, "upstream_error");
+    }
+    if (!await isIdentityAllowed(config.allowlist, config.revoke, identity)) {
+      sendJson(res, 403, { error: "forbidden" });
+      return;
+    }
+    const nowMs = now();
+    sendJson(res, 200, {
+      access_token: mintToken(secret, identity, "access", ttlSeconds, nowMs),
+      refresh_token: mintToken(secret, identity, "refresh", ttlSeconds, nowMs),
+      expires_in: ttlSeconds
+    });
+  }
+  async function refresh(req, res) {
+    const body = await readJsonBody(req);
+    const token = stringField(body, "refresh_token");
+    if (!token) throw new GateHttpError(403, "invalid_refresh_token");
+    const payload = verifyToken(secret, token);
+    if (!payload || payload.typ !== "refresh") throw new GateHttpError(403, "invalid_refresh_token");
+    if (payload.exp <= Math.floor(now() / 1e3)) throw new GateHttpError(403, "invalid_refresh_token");
+    if (!await isIdentityAllowed(config.allowlist, config.revoke, payload.sub)) {
+      sendJson(res, 403, { error: "forbidden" });
+      return;
+    }
+    sendJson(res, 200, {
+      access_token: mintToken(secret, payload.sub, "access", ttlSeconds, now()),
+      expires_in: ttlSeconds
+    });
+  }
+  async function authenticate(req, res) {
+    const token = bearerToken(req);
+    if (!token) {
+      sendJson(res, 401, { error: "unauthorized" });
+      return null;
+    }
+    let identity;
+    if (config.kind === "github") {
+      const payload = verifyToken(secret, token);
+      if (!payload || payload.typ !== "access" || payload.exp <= Math.floor(now() / 1e3)) {
+        sendJson(res, 401, { error: "unauthorized" });
+        return null;
+      }
+      identity = payload.sub;
+    } else {
+      identity = await resolveGoogleIdentity(config.verifyBearer, token);
+      if (!identity) {
+        sendJson(res, 401, { error: "unauthorized" });
+        return null;
+      }
+    }
+    if (!await isIdentityAllowed(config.allowlist, config.revoke, identity)) {
+      sendJson(res, 403, { error: "forbidden" });
+      return null;
+    }
+    return identity;
+  }
+  async function releaseManifest(req, res) {
+    if (await authenticate(req, res) === null) return;
+    let input;
+    try {
+      input = await config.release.manifest();
+    } catch {
+      throw new GateHttpError(500, "internal_error");
+    }
+    const created = new Date(now()).toISOString();
+    const manifest = {
+      version: input.version,
+      created,
+      files: input.files.map((file) => ({ path: file.path, sha256: file.sha256, size: file.size })),
+      signature: signManifest({ version: input.version, created, files: input.files }, config.release.sign)
+    };
+    sendJson(res, 200, manifest);
+  }
+  async function releaseFile(req, res, rawPath) {
+    if (await authenticate(req, res) === null) return;
+    const relativePath = safeReleasePath(rawPath);
+    if (!relativePath) {
+      sendJson(res, 404, { error: "not_found" });
+      return;
+    }
+    let bytes;
+    try {
+      bytes = await config.release.readFile(relativePath);
+    } catch {
+      sendJson(res, 404, { error: "not_found" });
+      return;
+    }
+    sendBytes(res, 200, bytes);
+  }
+}
+export {
+  buildCanonicalManifest,
+  canonicalJson,
+  createGateHandler,
+  fetchGitHubLogin,
+  isIdentityAllowed,
+  mapDeviceError,
+  mintToken,
+  normalizeGitHubApiBase,
+  pollDeviceToken,
+  requestDeviceCode,
+  resolveGoogleIdentity,
+  safeReleasePath,
+  sha256Hex,
+  signManifest,
+  verifyManifestSignature,
+  verifyReleaseFile,
+  verifySignedManifest,
+  verifyToken
+};

package/dist/release.d.ts

@@ -0,0 +1,34 @@
+import type { KeyObject } from 'node:crypto';
+import type { ReleaseFileEntry, SignedReleaseManifest } from './types.js';
+/** The UTF-8 canonical bytes a manifest signature is computed over. */
+export declare function buildCanonicalManifest(manifest: {
+    version: string;
+    created: string;
+    files: ReleaseFileEntry[];
+}): Buffer;
+/** Lowercase hex SHA-256 of the given bytes. */
+export declare function sha256Hex(bytes: Uint8Array): string;
+/** Signs a manifest with the injected Ed25519 signer and returns the base64 detached signature. */
+export declare function signManifest(manifest: {
+    version: string;
+    created: string;
+    files: ReleaseFileEntry[];
+}, sign: (canonicalBytes: Buffer) => Buffer): string;
+/**
+ * Documented verify helper for launchers. Returns true only when `signature` is a valid detached
+ * Ed25519 signature over the canonical bytes of `manifest`, checked against `publicKey`
+ * (a KeyObject or a PEM/DER string/Buffer). Never throws — a malformed signature is simply false.
+ */
+export declare function verifyManifestSignature(manifest: {
+    version: string;
+    created: string;
+    files: ReleaseFileEntry[];
+}, signature: string, publicKey: KeyObject | string | Buffer): boolean;
+/**
+ * Documented verify helper for launchers. Returns true only when `bytes` matches the manifest
+ * entry's `size` and SHA-256. A tampered body (or a manifest entry that does not describe the
+ * served bytes) is false.
+ */
+export declare function verifyReleaseFile(entry: ReleaseFileEntry, bytes: Uint8Array): boolean;
+/** Convenience: verify a full signed manifest against a public key. */
+export declare function verifySignedManifest(manifest: SignedReleaseManifest, publicKey: KeyObject | string | Buffer): boolean;

package/dist/tokens.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The gate's own access/refresh tokens.
+ *
+ * Format (documented): `<base64url(payload JSON)>.<base64url(HMAC-SHA256(payloadB64))>`.
+ * The payload is `{ sub, exp, jti, typ }` where `sub` is the identity (GitHub login or Google
+ * `sub`), `exp` is an epoch-seconds expiry, `jti` a random id, and `typ` is `'access'` or
+ * `'refresh'`. HMAC-SHA256 over a shared secret is the chosen signing scheme: the token only ever
+ * travels to the gate that minted it, so a symmetric MAC is sufficient and needs no keypair.
+ * Tokens are opaque to the client and must be treated as bearer credentials.
+ */
+export interface GateTokenPayload {
+    sub: string;
+    exp: number;
+    jti: string;
+    typ: 'access' | 'refresh';
+}
+/** Mints a signed token. `expiresInSeconds` is added to `nowMs`. */
+export declare function mintToken(secret: string, identity: string, typ: GateTokenPayload['typ'], expiresInSeconds: number, nowMs: number): string;
+/**
+ * Verifies a token's signature and shape. Returns the payload or null. Expiry is NOT checked here —
+ * callers compare `payload.exp` against their clock so the same token can be distinguished from a
+ * malformed one (expired refresh vs forged refresh).
+ */
+export declare function verifyToken(secret: string, token: string): GateTokenPayload | null;

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** One file in a release manifest. `path` is relative to the release root and is what
+ *  `GET /release/<path>` serves; `sha256` is the lowercase hex digest of the file bytes. */
+export interface ReleaseFileEntry {
+    path: string;
+    sha256: string;
+    size: number;
+}
+/** What `release.manifest()` returns: the gate stamps `created` and signs the result. */
+export interface ReleaseManifestInput {
+    version: string;
+    files: ReleaseFileEntry[];
+}
+/** The signed manifest exactly as `GET /release/manifest` returns it. */
+export interface SignedReleaseManifest {
+    version: string;
+    created: string;
+    files: ReleaseFileEntry[];
+    /** base64 (standard, padded) detached Ed25519 signature over `buildCanonicalManifest(manifest)`. */
+    signature: string;
+}
+/** Where the gate reads the set of identities allowed to install. */
+export interface AllowlistConfig {
+    /** `'logins'` is an explicit list served by `getLogins`. `'roster'` uses the SAME interface;
+     *  the adopter wires a roster adapter later (the gate treats both identically). */
+    source: 'roster' | 'logins';
+    /** Returns the allowed identities: GitHub logins for the `github` kind, `sub` claims for
+     *  the `google` kind. Absent (or throwing) means an empty allowlist — every identity is refused. */
+    getLogins?: () => Promise<string[]>;
+}
+/** How the gate serves a product's release artifacts. */
+export interface ReleaseConfig {
+    /** Describes the release to serve. Called per request so a re-released product is picked up. */
+    manifest: () => Promise<ReleaseManifestInput>;
+    /** Detached Ed25519 signer. Receives the exact canonical bytes and returns the raw signature. */
+    sign: (canonicalBytes: Buffer) => Buffer;
+    /** Reads one release file by manifest-relative path. Throws when absent. */
+    readFile: (path: string) => Promise<Buffer>;
+}
+interface GateConfigBase {
+    allowlist: AllowlistConfig;
+    release: ReleaseConfig;
+    /** Access-token lifetime in seconds. Default 3600; values above 3600 are clamped to 3600. */
+    tokenTtlSeconds?: number;
+    /** Explicit revocation list: identities that must be refused even if the allowlist still names
+     *  them. A function is re-read on every call, so a revocation takes effect on the next request. */
+    revoke?: string[] | (() => Promise<string[]>);
+    /** HMAC key for the gate's own access/refresh tokens. Absent, the github kind derives it from
+     *  `githubClientSecret`; the google kind generates an ephemeral one (it mints no tokens). */
+    tokenSecret?: string;
+    /** Injectable clock (epoch milliseconds). Tests use it to exercise expiry deterministically. */
+    now?: () => number;
+}
+export interface GitHubGateConfig extends GateConfigBase {
+    kind: 'github';
+    githubClientId: string;
+    /** Passed in by the adopter — never hardcoded in this library. */
+    githubClientSecret: string;
+    /** GitHub origin for the device flow. Default `https://github.com`; override for tests. */
+    githubApiBase?: string;
+}
+export interface GoogleGateConfig extends GateConfigBase {
+    kind: 'google';
+    /** Verifies a bearer token against the product's own OAuth server. Returns the identity or null. */
+    verifyBearer: (token: string) => Promise<{
+        sub: string;
+    } | null>;
+}
+export type GateConfig = GitHubGateConfig | GoogleGateConfig;
+/**
+ * A framework-agnostic node:http handler. Mount it as the fallback in the product's server:
+ * it owns `/gate/*` and `/release/*` and returns `true` after handling those; every other path
+ * returns `false` so the adopter's own router can continue.
+ */
+export type GateHandler = (req: IncomingMessage, res: ServerResponse) => boolean;
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mutmutco/installer-gate",
+  "version": "0.1.0",
+  "description": "Installer gate server library — GitHub device flow, allowlists, and signed release manifests. Mounted by a product's own server.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  }
+}