@fougere/core 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/builtins/logger.ts

@@ -0,0 +1,175 @@
+/**
+ * Fougere Logger — structured, colored, multi-runtime.
+ *
+ * Works on Node, Bun, Deno, Cloudflare Workers (console-based, no native bindings).
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+/**
+ * One line, before it was formatted for a terminal.
+ *
+ * The console form is already cooked — ANSI codes, a badge, a timestamp — so anything
+ * that wants to FORWARD a log needs it before that. What travels is the structure, and
+ * nothing here knows where it goes.
+ */
+export interface LogRecord {
+  level: Exclude<LogLevel, 'silent'>;
+  /** The logger's own name — 'boot:app', 'boot:app:catalog'. */
+  name: string;
+  message: string;
+  args: unknown[];
+  /** Epoch milliseconds. */
+  at: number;
+}
+
+export type LogSink = (record: LogRecord) => void;
+
+/**
+ * Who else takes this process's log lines, beside the console. A list, like the span
+ * sinks: a line is one fact, and forwarding it twice is the caller's business.
+ *
+ * Nothing is built when nobody listens — the record is only shaped if a sink exists.
+ */
+const sinks: LogSink[] = [];
+
+/** Take every line this process logs. Returns the way to withdraw. */
+export function onLog(next: LogSink): () => void {
+  sinks.push(next);
+  return () => {
+    const at = sinks.indexOf(next);
+    if (at >= 0) sinks.splice(at, 1);
+  };
+}
+
+const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+
+/**
+ * The level, held ONCE for the process and CONSULTED at every emission.
+ *
+ * It used to be copied into each Logger by the constructor, and copied again by
+ * `child()` — so there was no place where "the level" was, and changing it meant
+ * rebuilding every logger AND everything that had been handed one. A value read at
+ * the moment it is used costs the same and can move.
+ */
+let threshold: number = LEVELS[envLevel() ?? 'info'];
+
+/**
+ * The level the PROCESS was started with. Read here rather than only at `applyConfig`,
+ * which runs after the boot has already said where its root is — an operator asking for
+ * `warn` got that line anyway. Guarded: this module runs on Workers, where there is no
+ * `process`.
+ */
+export function envLevel(): LogLevel | undefined {
+  const raw = typeof process === 'undefined' ? undefined : process.env.FOUGERE_LOG_LEVEL;
+  return raw !== undefined && raw in LEVELS ? (raw as LogLevel) : undefined;
+}
+
+/**
+ * Set the level for every logger in this process, at once.
+ *
+ * Refuses a level it does not know rather than storing `undefined` as the threshold:
+ * every comparison against it is then `NaN`, so nothing is filtered and `logLevel()`
+ * reports its own fallback instead of what is in force.
+ */
+export function setLogLevel(level: LogLevel): void {
+  if (!(level in LEVELS)) {
+    throw new Error(`Unknown log level: '${level}'. One of ${Object.keys(LEVELS).join(', ')}.`);
+  }
+  threshold = LEVELS[level];
+}
+
+/** What the level is now — the dual, so a reload can report what it changed. */
+export function logLevel(): LogLevel {
+  return (Object.keys(LEVELS) as LogLevel[]).find((l) => LEVELS[l] === threshold) ?? 'info';
+}
+
+const COLORS: Record<string, string> = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+  gray: '\x1b[90m',
+};
+
+const LEVEL_STYLE: Record<string, { badge: string; color: string }> = {
+  debug: { badge: 'DBG', color: 'gray' },
+  info:  { badge: 'INF', color: 'green' },
+  warn:  { badge: 'WRN', color: 'yellow' },
+  error: { badge: 'ERR', color: 'red' },
+};
+
+function supportsColor(): boolean {
+  if (typeof process !== 'undefined') {
+    if (process.env.NO_COLOR) return false;
+    if (process.env.FORCE_COLOR === '1') return true;
+    return process.stdout?.isTTY === true;
+  }
+  return false;
+}
+
+function formatTime(): string {
+  const d = new Date();
+  const h = String(d.getHours()).padStart(2, '0');
+  const m = String(d.getMinutes()).padStart(2, '0');
+  const s = String(d.getSeconds()).padStart(2, '0');
+  const ms = String(d.getMilliseconds()).padStart(3, '0');
+  return `${h}:${m}:${s}.${ms}`;
+}
+
+export interface LoggerOptions {
+  /** Logger name / prefix. */
+  name?: string;
+  /** Force color on/off. Auto-detected by default. */
+  color?: boolean;
+}
+
+export class Logger {
+  private name: string;
+  private color: boolean;
+
+  constructor(prefix?: string, options?: Omit<LoggerOptions, 'name'>) {
+    this.name = prefix ?? 'app';
+    this.color = options?.color ?? supportsColor();
+  }
+
+  /** Create a child logger with a sub-name. It carries no level of its own either. */
+  child(name: string): Logger {
+    return new Logger(`${this.name}:${name}`, { color: this.color });
+  }
+
+  debug(msg: string, ...args: unknown[]) { this.log('debug', msg, args); }
+  info(msg: string, ...args: unknown[])  { this.log('info', msg, args); }
+  warn(msg: string, ...args: unknown[])  { this.log('warn', msg, args); }
+  error(msg: string, ...args: unknown[]) { this.log('error', msg, args); }
+
+  private log(level: string, msg: string, args: unknown[]) {
+    if (LEVELS[level as LogLevel] < threshold) return;
+
+    // Beside the console, never instead of it: a forwarded line is an addition, and a
+    // sink that throws must not cost the operator the line they were reading.
+    for (const take of sinks) {
+      try {
+        take({ level: level as LogRecord['level'], name: this.name, message: msg, args, at: Date.now() });
+      } catch { /* forwarding never breaks logging */ }
+    }
+
+    const style = LEVEL_STYLE[level];
+    const time = formatTime();
+    // One console method per level. `debug` and `info` both went to `console.log`, so
+    // nothing downstream — a terminal filter, a collector — could tell them apart.
+    const method = level as 'debug' | 'info' | 'warn' | 'error';
+
+    if (this.color) {
+      const c = COLORS[style.color];
+      const prefix = `${COLORS.dim}${time}${COLORS.reset} ${c}${COLORS.bold}${style.badge}${COLORS.reset} ${COLORS.magenta}${this.name}${COLORS.reset}`;
+      console[method](prefix, msg, ...args);
+    } else {
+      console[method](`${time} ${style.badge} [${this.name}]`, msg, ...args);
+    }
+  }
+}

package/src/config-loader.ts

@@ -0,0 +1,146 @@
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { AuthConfig } from './boot/auth.js';
+import type { LogLevel } from './builtins/logger.js';
+import type { ConventionsInput } from './scan/conventions.js';
+import { getModuleLoader } from './loader.js';
+
+// ── Types ────────────────────────────────────────
+
+export interface FougereConfig {
+  /** Database configuration — the DEFAULT source, the one an entity lands in unnamed. */
+  db?: 'sqlite' | { dialect: 'sqlite'; path?: string } | false;
+  /**
+   * The other places rows live — a name, an engine, and the entities it holds.
+   *
+   * A fact about the APP, stated beside `remotes:` because it is the same kind of
+   * statement: `remotes:` says where a CALL goes, this says where a ROW is. Neither
+   * belongs on the entity, which describes itself and not its deployment.
+   *
+   * Only the exception is declared: everything unnamed stays in `db`. Membership is
+   * per ENTITY rather than per frond — two fronds may share a database, and one frond
+   * may hold entities in two — so the entity is the truth and a frond-wide shorthand
+   * waits for a case that needs it.
+   *
+   * A `ref()` across two sources gets no foreign key: two databases share no
+   * constraint. The DDL stops pretending rather than the `ref` being refused.
+   */
+  sources?: Record<string, { dialect?: 'sqlite'; path?: string; entities: string[] }>;
+  /**
+   * The names the scan reads instead of deriving them — the import scope, the fronds
+   * directory, the seven convention directories.
+   *
+   * Only what differs is stated. Read BEFORE the fronds are discovered, which is what
+   * lets it name the prefix they are found under: nothing in this file may import
+   * `@fronds/*`, or the name would be needed to read the file that declares it.
+   */
+  conventions?: ConventionsInput;
+  /**
+   * How much every logger says. The one key a running app CONSULTS rather than
+   * consumes, so re-reading this file changes it without rebuilding anything.
+   *
+   * `FOUGERE_LOG_LEVEL` still wins — it is how the CLI speaks, and the precedence is
+   * the usual one (CLI over config file).
+   */
+  logLevel?: LogLevel;
+  /** Remote fronds — frondName → base URL. */
+  remotes?: Record<string, string>;
+  /**
+   * Which realization answers which port — port class name → implementation class name.
+   *
+   * A fact about the APP, stated beside `remotes:` for the same reason `sources:` is:
+   * `remotes:` says where a CALL goes, `sources:` says where a ROW is, this says who
+   * performs an ACTION. None of the three belongs inside the frond, which describes
+   * itself and not its deployment — a `billing` frond naming Stripe would be the one
+   * thing the framework refuses.
+   *
+   * Only the exception is declared. One class extending a port answers it by
+   * convention and this key stays absent; two make the boot refuse until one is named.
+   */
+  ports?: Record<string, string>;
+  /** Auth declaration — picks a provider package and forwards options to it. */
+  auth?: AuthConfig;
+  /**
+   * Which protocol adapters this app serves.
+   *
+   * A fact about the APP, declared once beside `db`, `remotes` and `auth` — not a
+   * property of whichever host runs it. Before this existed the same decision was
+   * spelled five different ways: Nuxt mounted REST unconditionally, the Web hosts
+   * served it if you happened to create a route file, and Express if you happened to
+   * call a middleware. One decision, five dialects, no canonical place.
+   *
+   * Absent means not served. The call envelope is not listed here: it is the wire the
+   * client primitives use, not a projection an app chooses to publish.
+   */
+  adapters?: AdapterConfig;
+}
+
+/** Protocol adapters, by the name of the package that provides them. */
+export interface AdapterConfig {
+  /** `@fougere/adapter-rest` — REST under `/api/{frond}/{plural}`. */
+  rest?: boolean;
+  /** `@fougere/adapter-graphql` — a GraphQL schema over the same operations. */
+  graphql?: boolean;
+  /** A surface of your own; the framework only records that you declared it. */
+  [adapter: string]: boolean | undefined;
+}
+
+// ── Loading ──────────────────────────────────────
+
+const CONFIG_FILES = ['fougere.config.ts', 'fougere.config.js', 'fougere.config.mjs'];
+
+async function loadConfigFrom(dir: string, fresh?: boolean): Promise<FougereConfig> {
+  const loader = getModuleLoader();
+  for (const file of CONFIG_FILES) {
+    const path = resolve(dir, file);
+    if (existsSync(path)) {
+      // A module is cached by its specifier, so a second load of an EDITED file hands
+      // back what was read the first time — measured, and it made re-reading a config
+      // return the config already in force. The loader owns its own cache, so it is the
+      // one told; the old module stays in memory, re-reading being for a change.
+      const mod = await loader(path, fresh ? { fresh } : undefined);
+      return ((mod as { default?: FougereConfig }).default ?? mod) as FougereConfig;
+    }
+  }
+  return {};
+}
+
+/**
+ * Load the root fougere.config.{ts,js,mjs} from the given directory.
+ *
+ * `fresh` re-reads a file that may have changed since the last load — what a host
+ * calls when it decides to reconsider its config, and the only way `applyConfig` has
+ * anything new to apply.
+ */
+export async function loadConfig(root: string, options?: { fresh?: boolean }): Promise<FougereConfig> {
+  return loadConfigFrom(root, options?.fresh);
+}
+
+// ── Merging ──────────────────────────────────────
+
+/**
+ * Override a config with another, the invariant of every cascade level:
+ * scalar keys replace, but `remotes` (the topology) MERGES — an override adds
+ * or redirects a frond without erasing the others. Used for workspace→app and
+ * for global→CLI alike.
+ */
+function mergeGlobal(base: FougereConfig, override: Partial<FougereConfig>): FougereConfig {
+  const merged: FougereConfig = { ...base, ...override };
+  if (base.remotes || override.remotes) {
+    merged.remotes = { ...base.remotes, ...override.remotes };
+  }
+  return merged;
+}
+
+/**
+ * Load config along the workspace→app frontier. The workspace-root config is
+ * the base (canonical topology: `remotes`, shared `db`); the app-root config
+ * overrides. Same `root` boundary the fronds already cascade along. When both
+ * roots resolve to the same dir (single app, no workspace), this is the plain
+ * root config — idempotent, no behavior change.
+ */
+export async function loadCascadedConfig(workspaceRoot: string, appRoot: string): Promise<FougereConfig> {
+  const base = await loadConfig(workspaceRoot);
+  if (resolve(workspaceRoot) === resolve(appRoot)) return base;
+  return mergeGlobal(base, await loadConfig(appRoot));
+}

package/src/contract/Call.ts

@@ -0,0 +1,18 @@
+import { Invocation, type InvocationInput } from './Invocation.js';
+import type { RouteAddress } from './RouteAddress.js';
+
+/** One normalized request: where it goes and what the caller supplied. */
+export class Call {
+  readonly address: RouteAddress;
+  readonly invocation: Invocation;
+
+  constructor(address: RouteAddress, invocation?: InvocationInput) {
+    this.address = address;
+    this.invocation = Invocation.from(invocation);
+    Object.freeze(this);
+  }
+
+  withInvocation(invocation: Invocation): Call {
+    return new Call(this.address, invocation);
+  }
+}

package/src/contract/Invocation.ts

@@ -0,0 +1,72 @@
+export interface InvocationContext {
+  params: Record<string, unknown>;
+  query: Record<string, unknown>;
+  body: unknown;
+  state: Record<string, unknown>;
+  trace?: string;
+  identity?: string;
+  caller?: string;
+}
+
+export type InvocationInput = Partial<InvocationContext>;
+
+function canonicalValue(value: unknown): unknown {
+  if (value === null || value === undefined || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return Object.freeze(value.map(canonicalValue));
+
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return value;
+  return canonicalRecord(value);
+}
+
+function canonicalRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return Object.freeze({});
+
+  const result: Record<string, unknown> = {};
+  for (const [key, member] of Object.entries(value)) {
+    if (member !== undefined) result[key] = canonicalValue(member);
+  }
+  return Object.freeze(result);
+}
+
+/** Canonical invocation shared by every entry and transport. */
+export class Invocation implements InvocationContext {
+  readonly params: Record<string, unknown>;
+  readonly query: Record<string, unknown>;
+  readonly body: unknown;
+  readonly state: Record<string, unknown>;
+  readonly trace?: string;
+  readonly identity?: string;
+  readonly caller?: string;
+
+  private constructor(input: InvocationInput) {
+    this.params = canonicalRecord(input.params);
+    this.query = canonicalRecord(input.query);
+    this.body = canonicalValue(input.body);
+    // State is host-owned and may still be enriched by existing middlewares. Moving it
+    // to immutable lifecycle context is a separate migration.
+    this.state = input.state ?? {};
+    if (input.trace !== undefined) this.trace = input.trace;
+    if (input.identity !== undefined) this.identity = input.identity;
+    if (input.caller !== undefined) this.caller = input.caller;
+    Object.freeze(this);
+  }
+
+  static from(input?: InvocationInput): Invocation {
+    return input instanceof Invocation ? input : new Invocation(input ?? {});
+  }
+
+  withBody(body: unknown): Invocation {
+    return new Invocation({ ...this, body });
+  }
+
+  withState(state: Record<string, unknown>): Invocation {
+    return new Invocation({ ...this, state });
+  }
+}
+
+export const EMPTY_INVOCATION = Invocation.from();
+
+export function canonicalInvocation(input?: InvocationInput): Invocation {
+  return Invocation.from(input);
+}

package/src/contract/RouteAddress.ts

@@ -0,0 +1,49 @@
+export interface RouteAddressInput {
+  entity: string;
+  operation: string;
+  surface?: string;
+}
+
+function required(value: string, name: string): string {
+  if (value.trim().length === 0) throw new TypeError(`Route ${name} cannot be empty`);
+  return value;
+}
+
+function optional(value: string | undefined, name: string): string | undefined {
+  return value === undefined ? undefined : required(value, name);
+}
+
+/** Canonical identity of one callable operation. */
+export class RouteAddress {
+  readonly entity: string;
+  readonly operation: string;
+  readonly surface?: string;
+
+  constructor(input: RouteAddressInput) {
+    this.entity = required(input.entity, 'entity');
+    this.operation = required(input.operation, 'operation');
+    this.surface = optional(input.surface, 'surface');
+    Object.freeze(this);
+  }
+
+  key(): string {
+    return JSON.stringify([this.surface ?? null, this.entity, this.operation]);
+  }
+
+  equals(other: RouteAddress): boolean {
+    return this.key() === other.key();
+  }
+
+  toString(): string {
+    const audience = this.surface ? `${this.surface}/` : '';
+    return `${audience}${this.entity}.${this.operation}`;
+  }
+
+  toJSON(): RouteAddressInput {
+    return {
+      entity: this.entity,
+      operation: this.operation,
+      ...(this.surface !== undefined ? { surface: this.surface } : {}),
+    };
+  }
+}

package/src/contract.ts

@@ -0,0 +1,74 @@
+/**
+ * Contract surface — what a sender needs to speak to a receiver, and
+ * nothing that assumes a runtime: the error vocabulary, the invocation
+ * shape, the call value, the naming convention.
+ *
+ * Browser-safe by design: no node builtin may enter this module's import
+ * graph. Published as the `@fougere/core/contract` subpath so client
+ * bundles never touch the full index (scanner, config loader). `@fougere/schema`
+ * is allowed in — measured, it imports no node builtin either.
+ */
+import { lowerFirst } from '@fougere/schema';
+import { canonicalInvocation, type InvocationContext } from './wire/invocation.js';
+import type { FrondCall } from './wire/call.js';
+
+export { FougereError, ErrorCode, validationErrorsOf } from './wire/errors.js';
+// A receiver turns a refusal into what may cross a process boundary, and it is not
+// core's boot — reaching it through the main entry dragged the scanner into a bundle.
+export { toPublicError } from './wire/http-error.js';
+export type { FougereErrorOptions } from './wire/errors.js';
+export { canonicalInvocation, EMPTY_INVOCATION } from './wire/invocation.js';
+export type { InvocationContext } from './wire/invocation.js';
+export { Invocation } from './contract/Invocation.js';
+export type { InvocationInput } from './contract/Invocation.js';
+export { Call } from './contract/Call.js';
+export { RouteAddress } from './contract/RouteAddress.js';
+export type { RouteAddressInput } from './contract/RouteAddress.js';
+export type { FrondCall, Transport, SignedCall } from './wire/call.js';
+
+/**
+ * What `rpc.discover` answers. It belongs here and not to the runtime: the
+ * reserved op travels on the same wire as every other call, so a consumer that
+ * only sends — a browser bundle, a frond written elsewhere — needs its shape and
+ * nothing else. Type-only, so `call.js` never enters the runtime graph.
+ *
+ * Stated once, on purpose: two private copies of this interface have already gone
+ * stale (the CLI's, then the Rust demo's) the day an op stopped being a bare name.
+ */
+export type { IdentityCard, CardOp, TopologyReport, FrondPlacement, Edge } from './wire/call.js';
+export { assertIdentityCard } from './wire/call.js';
+
+/**
+ * The key a class name is filed under — 'Post' → 'post'. Re-exported rather than
+ * respelled: a card writes it and a foreign key derives from it, so the convention
+ * belongs to the schema, and a second copy here is a second opinion. It travels
+ * through this subpath because a consumer of the wire (a browser bundle) may hold no
+ * schema dependency of its own — that audience only. Inside the package it is read from
+ * `@fougere/schema` directly: routing four modules through here bought nothing and put
+ * this file inside a cycle.
+ */
+export { lowerFirst } from '@fougere/schema';
+
+/** A call, fully fabricated: the designation and its completed invocation. */
+export interface CallValue {
+  call: FrondCall;
+  invocation: InvocationContext;
+}
+
+/**
+ * Fabricate the call value — one designation, two spellings:
+ * `callValueOf(Post, 'list', { query })` (class + verb) or
+ * `callValueOf({ entity, op }, input)` (raw, for dynamic bridges).
+ * Missing invocation fields complete to the empty invocation.
+ */
+export function callValueOf(
+  target: { name: string } | FrondCall,
+  opOrInput?: string | Partial<InvocationContext>,
+  input?: Partial<InvocationContext>,
+): CallValue {
+  const [call, given] =
+    typeof opOrInput === 'string'
+      ? [{ entity: lowerFirst((target as { name: string }).name), op: opOrInput }, input]
+      : [target as FrondCall, opOrInput];
+  return { call, invocation: canonicalInvocation(given) };
+}

package/src/crypto/encoding.ts

@@ -0,0 +1,59 @@
+/**
+ * What both realizations spell identically — bytes in, bytes out, no platform.
+ *
+ * `Buffer` did all of this and does not exist on a Worker; `atob`/`btoa` exist on both.
+ * Nothing here is a policy decision, which is why it sits beside the port rather than
+ * inside either half: two copies of a base64url would be two chances to disagree on the
+ * padding, and the disagreement would show up as a bad signature.
+ */
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export const bytesOf = (text: string): Uint8Array => encoder.encode(text);
+export const textOf = (bytes: Uint8Array): string => decoder.decode(bytes);
+
+/** Base64url, unpadded — what JWS puts between the dots. */
+export function b64url(input: Uint8Array | string): string {
+  const bytes = typeof input === 'string' ? bytesOf(input) : input;
+  let binary = '';
+  // One character at a time: `String.fromCharCode(...bytes)` overflows the argument
+  // limit on a key, and a signature is small enough that the loop costs nothing.
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function unb64url(input: string): Uint8Array {
+  const binary = atob(input.replace(/-/g, '+').replace(/_/g, '/'));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** Plain base64, padded — what an environment variable carries a PEM as. */
+export function b64(input: Uint8Array | string): string {
+  const bytes = typeof input === 'string' ? bytesOf(input) : input;
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export const unb64 = (input: string): Uint8Array => {
+  const binary = atob(input);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+};
+
+/**
+ * The DER a PEM wraps. WebCrypto imports DER and knows nothing about the armour.
+ *
+ * The label is not checked: a caller asking for a private key and handed a public one
+ * fails at `importKey` with a message about the key, which is the truer error than one
+ * about a header line.
+ */
+export function derOf(pem: string): Uint8Array {
+  const body = pem.replace(/-----(BEGIN|END)[^-]+-----/g, '').replace(/\s+/g, '');
+  if (body.length === 0) throw new Error('Not a PEM: no base64 body between the armour');
+  return unb64(body);
+}

package/src/crypto/node.ts

@@ -0,0 +1,30 @@
+/**
+ * Ed25519 through `node:crypto` — the default realization, and the fast one.
+ *
+ * `sign`/`verify` are synchronous here and stay synchronous: the promise is put around
+ * the answer, never around the work. That is the whole reason this file exists rather
+ * than everyone sharing the WebCrypto half.
+ */
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
+import type { CryptoPort, PublicJwk, Signer, Verifier } from './port.js';
+
+export const crypto: CryptoPort = {
+  async sha256(data) {
+    return new Uint8Array(createHash('sha256').update(data).digest());
+  },
+
+  async signerOf(privateKeyPem): Promise<Signer> {
+    // Parsed here and captured, so a call signs against a KeyObject and never a string.
+    const key = createPrivateKey(privateKeyPem);
+    return { async sign(data) { return new Uint8Array(sign(null, data, key)); } };
+  },
+
+  async verifierOf(key): Promise<Verifier> {
+    const parsed = typeof key === 'string'
+      ? createPublicKey(key)
+      : createPublicKey({ key: key as never, format: 'jwk' });
+    return { async verify(data, signature) { return verify(null, data, parsed, signature); } };
+  },
+};
+
+export type { CryptoPort, PublicJwk, Signer, Verifier };

package/src/crypto/port.ts

@@ -0,0 +1,45 @@
+/**
+ * The two Ed25519 gestures a signed call needs, and the one hash that binds it.
+ *
+ * Node signs 59% faster than WebCrypto on the same curve (measured 2026-08-23: 14.30 µs
+ * against 22.72 µs per signature, 34.42 against 41.81 to verify), so this is a PORT with
+ * two realizations and not one implementation at the lowest common denominator. `#crypto`
+ * resolves to `crypto/node.ts` everywhere except under the `workerd` condition — the
+ * bundler picks at build time, and neither half ever appears in the other's output.
+ *
+ * The shape is async because WebCrypto is. On Node that costs one microtask, which the
+ * same measurement puts inside the noise of the signature itself (14.30 sync against
+ * 14.28 awaited) — awaiting is free, converting is not.
+ *
+ * A KEY IS PARSED ONCE. `crypto.subtle.importKey` is async and per-key, so an interface
+ * shaped `sign(key, data)` would import on every call; `signerOf(pem)` hands back
+ * something that holds the parsed key, and a boot builds it once.
+ */
+
+/** A parsed private key. */
+export interface Signer {
+  sign(data: Uint8Array): Promise<Uint8Array>;
+}
+
+/** A parsed public key. */
+export interface Verifier {
+  /** False, never a throw: a bad signature is an answer, not a failure. */
+  verify(data: Uint8Array, signature: Uint8Array): Promise<boolean>;
+}
+
+/** A public key as a grant carries it — `{ kty: 'OKP', crv: 'Ed25519', x }`. */
+export interface PublicJwk {
+  kty: string;
+  crv?: string;
+  x?: string;
+  [key: string]: unknown;
+}
+
+export interface CryptoPort {
+  /** SHA-256. What binds a body to an envelope without carrying the body. */
+  sha256(data: Uint8Array): Promise<Uint8Array>;
+  /** From a PKCS#8 PEM — what `fougere keys` writes. */
+  signerOf(privateKeyPem: string): Promise<Signer>;
+  /** From an SPKI PEM (the root's) or a JWK (the one a grant embeds). */
+  verifierOf(key: string | PublicJwk): Promise<Verifier>;
+}