akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/server/memoryLimit.ts

@@ -1,13 +1,5 @@
 import fs from "node:fs";
 
-/**
- * Where a process's RSS ceiling comes from, shared by every host that recycles a child to bound it.
- *
- * A budget can be declared explicitly, discovered from the container, or absent altogether, so each
- * host asks for a fraction of whatever limit it can find and supplies its own fallback for the last
- * case. Kept as its own module rather than living on a host class because both `akanjs/server` and
- * the dev host in `@akanjs/devkit` need it, and neither should import the other's stack to get it.
- */
 export class MemoryLimit {
   static readonly #cgroupLimitFiles = ["/sys/fs/cgroup/memory.max", "/sys/fs/cgroup/memory/memory.limit_in_bytes"];
   /** Host-level cgroup files report effectively-unlimited sentinels; anything this large means "no limit". */
@@ -47,11 +39,7 @@ export class MemoryLimit {
     return null;
   }
 
-  /**
-   * Resolves a ceiling from, in order: an explicit MiB env, an explicit byte env, a fraction of the
-   * container's memory limit, and finally the caller's fallback (`null` to leave the process
-   * unbounded).
-   */
+  /** Order: MiB env, byte env, `limitFraction` of the container limit, then `fallbackBytes` (`null` = unbounded). */
   static resolveMaxRssBytes({
     megabytesEnv,
     bytesEnv,

package/server/oauth/OAuthAuthorize.ts

@@ -4,7 +4,7 @@ import { OAuthRedirect } from "./OAuthRedirect";
 import type { OAuthAuthorizeErrorCode, OAuthAuthorizeParams, OAuthClientRecord } from "./oauthTypes";
 
 export interface OAuthAuthorizeContext {
-  /** The client the request's `client_id` resolved to, however it was registered; `null` when it resolved to nothing. */
+  /** `null` when the request's `client_id` resolved to no client. */
   client: OAuthClientRecord | null;
   issuer: string;
   /** The one resource this server issues tokens for — the MCP endpoint's canonical URL. */
@@ -14,11 +14,7 @@ export interface OAuthAuthorizeContext {
 export type OAuthAuthorizeResult = { ok: true; params: OAuthAuthorizeParams } | { ok: false; response: Response };
 
 export class OAuthAuthorize {
-  /**
-   * Validates in the order RFC 6749 §4.1.2.1 prescribes: the client and its redirect URI first, answered with a page
-   * because nothing may be redirected to an unverified destination; everything after that is answered through the
-   * redirect URI the client registered, with `state` and `iss` so the client can match and trust the answer.
-   */
+
   static parse(url: URL, { client, issuer, resource }: OAuthAuthorizeContext): OAuthAuthorizeResult {
     const param = (name: string) => url.searchParams.get(name) ?? undefined;
     const clientId = param("client_id");
@@ -48,7 +44,7 @@ export class OAuthAuthorize {
       return fail("unauthorized_client", "This client is not registered for the authorization_code grant.");
     const codeChallenge = param("code_challenge");
     const method = param("code_challenge_method");
-
+    
     if (method !== undefined && method !== OAuthPkce.method)
       return fail("invalid_request", `code_challenge_method "${method}" is not supported; use ${OAuthPkce.method}.`);
     if (!OAuthPkce.isChallenge(codeChallenge)) return fail("invalid_request", "A PKCE code_challenge is required.");

package/server/oauth/OAuthClientIdMetadata.ts

@@ -5,7 +5,7 @@ import type { OAuthClientRecord, OAuthRedirectPolicy } from "./oauthTypes";
 
 export interface OAuthClientIdMetadataResult {
   client: OAuthClientRecord;
-  /** How long the document may be reused, from its `Cache-Control`, clamped to something a server can live with. */
+  /** From `Cache-Control` max-age (else `defaultTtlMs`), clamped to `minTtlMs`..`maxTtlMs`. */
   ttlMs: number;
 }
 
@@ -15,18 +15,10 @@ export type OAuthDocumentFetch = (input: string | URL | Request, init?: RequestI
 
 export interface OAuthClientIdMetadataFetchOptions extends OAuthRedirectPolicy {
   fetchImpl?: OAuthDocumentFetch;
-  /**
-   * Resolves the document's host before it is fetched and refuses one whose addresses are not all public. On by
-   * default with the system resolver; `false` trusts the name alone, for a deployment whose egress policy already
-   * closes the private range.
-   */
+  /** SSRF check: every resolved address must be public. Default: system resolver; `false` trusts the name alone. */
   resolve?: OAuthAddressLookup | false;
 }
 
-/**
- * OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document): a client whose `client_id`
- * is an HTTPS URL hosts its own registration there, and the server reads it instead of holding a registry.
- */
 export class OAuthClientIdMetadata {
   static readonly maxBytes = 64 * 1024;
   static readonly timeoutMs = 5_000;
@@ -40,13 +32,6 @@ export class OAuthClientIdMetadata {
     return !!url && url.protocol === "https:" && url.pathname !== "/" && !url.username && !url.password;
   }
 
-  /**
-   * Whether a document URL may be fetched on the client's say-so. The fetch API never shows the address a name
-   * resolved to, so this judges the name: no address literals (a client hosts its document under a name), no
-   * single-label or reserved-suffix names, no explicit port. A public name that resolves into the private range is
-   * `resolvesPublicly`'s to catch; the rebinding window between that lookup and the fetch is the residual the
-   * deployment's egress policy owns — the SSRF section of the draft says as much.
-   */
   static isFetchable(url: URL): boolean {
     const host = url.hostname.toLowerCase();
     if (url.port) return false;
@@ -55,11 +40,6 @@ export class OAuthClientIdMetadata {
     return !/\.(?:localhost|local|internal|lan|home|arpa)$/.test(host);
   }
 
-  /**
-   * Whether every address the name resolves to is public. The resolver is asked separately from the fetch, so a
-   * name that flips between the two (DNS rebinding) is the residual; what this closes is the ordinary case of a
-   * public name parked on a private address, which `isFetchable` cannot see.
-   */
   static async resolvesPublicly(hostname: string, resolve: OAuthAddressLookup = OAuthClientIdMetadata.#lookup) {
     try {
       const addresses = await resolve(hostname);
@@ -96,10 +76,6 @@ export class OAuthClientIdMetadata {
     return client ? { client, ttlMs: OAuthClientIdMetadata.#ttl(res.headers.get("cache-control")) } : null;
   }
 
-  /**
-   * §4: `client_id` MUST equal the URL the document was fetched from, `client_name` and `redirect_uris` MUST be
-   * present. Only public clients are accepted — `private_key_jwt` needs a JWKS the token endpoint does not read.
-   */
   static validate(clientId: string, json: unknown, policy: OAuthRedirectPolicy = {}): OAuthClientRecord | null {
     if (!json || typeof json !== "object" || Array.isArray(json)) return null;
     const doc = json as Record<string, unknown>;
@@ -122,7 +98,6 @@ export class OAuthClientIdMetadata {
     };
   }
 
-  /** The system resolver, under the same deadline as the fetch: a resolver that hangs is a fetch that hangs. */
   static readonly #lookup: OAuthAddressLookup = async (hostname) =>
     await Promise.race([
       lookup(hostname, { all: true }),

package/server/oauth/OAuthErrors.ts

@@ -15,10 +15,6 @@ export class OAuthErrors {
   
   static readonly noStore = { "cache-control": "no-store", pragma: "no-cache" } as const;
 
-  /**
-   * RFC 6749 §5.2. `invalid_client` is 401, and when the client authenticated with the `Authorization` header the
-   * answer names that scheme back — the one case the RFC requires a `WWW-Authenticate` on a token response.
-   */
   static token(
     error: OAuthTokenErrorCode,
     description: string,
@@ -37,11 +33,6 @@ export class OAuthErrors {
     return Response.json({ error, error_description: description }, { status: 400, headers: OAuthErrors.noStore });
   }
 
-  /**
-   * An authorization error that travels back through the redirect URI (RFC 6749 §4.1.2.1) — legal only once that
-   * URI has been matched against the client's registration, which is why `OAuthAuthorize` answers the client and
-   * redirect checks with a page instead.
-   */
   static redirect(
     redirectUri: string,
     { error, description, state, iss }: OAuthRedirectParams & { error: OAuthAuthorizeErrorCode; description?: string },
@@ -53,10 +44,6 @@ export class OAuthErrors {
     return OAuthErrors.#located(redirectUri, { code, state, iss });
   }
 
-  /**
-   * The answer when nothing may be redirected to: an unknown client or an unregistered redirect URI, where the
-   * destination the request named is the one thing that cannot be trusted with the user (RFC 6749 §4.1.2.1).
-   */
   static page(status: number, title: string, detail: string) {
     const body = `<!doctype html><meta charset="utf-8"><title>${OAuthErrors.#escape(title)}</title><main style="font:16px system-ui;max-width:32rem;margin:4rem auto"><h1>${OAuthErrors.#escape(title)}</h1><p>${OAuthErrors.#escape(detail)}</p></main>`;
     return new Response(body, {

package/server/oauth/OAuthMetadata.ts

@@ -5,19 +5,13 @@ export interface OAuthMetadataProps {
   registrationEndpoint?: string;
   revocationEndpoint?: string;
   scopesSupported?: string[];
-  /** Whether a `client_id` that is an HTTPS URL is read as a metadata document. Advertised as true unless a deployment turned it off. */
+  /** Whether an HTTPS `client_id` is read as a metadata document; defaults to `true`. */
   clientIdMetadataDocumentSupported?: boolean;
 }
 
 export class OAuthMetadata {
   static readonly wellKnownSuffix = "/.well-known/oauth-authorization-server";
 
-  /**
-   * The RFC 8414 document. Three fixed fields are load-bearing for MCP clients: `code_challenge_methods_supported`
-   * (a client MUST refuse to proceed without it), `client_id_metadata_document_supported` (the registration path the
-   * spec prefers), and `authorization_response_iss_parameter_supported` (which is what obliges the client to check
-   * `iss` on the way back).
-   */
   static document({
     issuer,
     authorizationEndpoint,

package/server/oauth/OAuthPkce.ts

@@ -1,9 +1,7 @@
 import { createHash, timingSafeEqual } from "node:crypto";
 
-/** RFC 7636 with `S256` only: OAuth 2.1 drops `plain`, and an MCP client refuses a server whose metadata offers nothing else. */
 export class OAuthPkce {
   static readonly method = "S256";
-  
   static readonly #verifier = /^[A-Za-z0-9\-._~]{43,128}$/;
   
   static readonly #challenge = /^[A-Za-z0-9\-_]{43}$/;

package/server/oauth/OAuthRedirect.ts

@@ -18,11 +18,6 @@ export class OAuthRedirect {
     return url.protocol === "http:" && OAuthRedirect.loopbackHosts.has(url.hostname);
   }
 
-  /**
-   * What may be registered: HTTPS, loopback HTTP, or a private-use scheme the deployment named. The MCP spec allows
-   * only the first two; the third exists because Cursor's desktop client registers `cursor://…/oauth/callback`, and
-   * a server that refuses it cannot be used from Cursor at all.
-   */
   static isRegistrable(uri: string, { allowedSchemes = [] }: OAuthRedirectPolicy = {}): boolean {
     const url = OAuthRedirect.parse(uri);
     if (!url) return false;
@@ -30,10 +25,6 @@ export class OAuthRedirect {
     return allowedSchemes.includes(url.protocol.slice(0, -1));
   }
 
-  /**
-   * Exact match against what was registered, except that a loopback redirect may vary its port: a native client
-   * binds whichever port is free at the time (RFC 8252 §7.3), and Claude Code picks one at random per session.
-   */
   static matches(registered: readonly string[], presented: string): boolean {
     if (registered.includes(presented)) return true;
     const url = OAuthRedirect.parse(presented);

package/server/oauth/OAuthRegistration.ts

@@ -4,7 +4,6 @@ import type { OAuthClientAuthMethod, OAuthClientMetadata, OAuthClientRecord, OAu
 
 export type OAuthRegistrationResult = { ok: true; client: OAuthClientMetadata } | { ok: false; response: Response };
 
-/** RFC 7591 Dynamic Client Registration — the request's validation and the response's shape; the identifier is the caller's. */
 export class OAuthRegistration {
   static readonly authMethods: readonly OAuthClientAuthMethod[] = ["none", "client_secret_post", "client_secret_basic"];
   static readonly grantTypes: readonly string[] = ["authorization_code", "refresh_token"];
@@ -70,7 +69,6 @@ export class OAuthRegistration {
     return Array.isArray(value) && value.every((entry) => typeof entry === "string");
   }
 
-  /** The list as sent when every entry is allowed, the default when absent, `null` when something else was named. */
   static #subset(value: unknown, allowed: readonly string[], fallback: string[]): string[] | null {
     if (value === undefined) return fallback;
     if (!OAuthRegistration.#strings(value) || !value.length) return null;

package/server/oauth/OAuthRevocation.ts

@@ -6,7 +6,7 @@ export type OAuthTokenTypeHint = "access_token" | "refresh_token";
 
 export interface OAuthRevocationParams {
   token: string;
-  /** The client's guess at what it is handing over; a server may ignore it, and an unknown hint reads as none. */
+  /** Advisory only; an unknown hint reads as none. */
   tokenTypeHint?: OAuthTokenTypeHint;
   client: OAuthClientCredential;
 }
@@ -15,14 +15,9 @@ export type OAuthRevocationParseResult =
   | { ok: true; params: OAuthRevocationParams }
   | { ok: false; response: Response };
 
-/**
- * RFC 7009 Token Revocation — the request's shape and the two answers it allows. What a token *is* and whose it
- * is are the issuer's to decide, so the parse hands back the credential and the token and nothing more.
- */
 export class OAuthRevocation {
   static readonly hints: readonly OAuthTokenTypeHint[] = ["access_token", "refresh_token"];
 
-  /** §2.1: form-encoded like the token endpoint, with the same client authentication and `token` required. */
   static async parse(req: Request): Promise<OAuthRevocationParseResult> {
     const type = req.headers.get("content-type")?.toLowerCase() ?? "";
     if (!type.startsWith("application/x-www-form-urlencoded"))
@@ -45,11 +40,6 @@ export class OAuthRevocation {
     };
   }
 
-  /**
-   * §2.2: a revoked token and a token the server never knew get the same empty 200, so the endpoint cannot be used
-   * to test whether a token exists. The only refusals are a malformed request and a client that failed to
-   * authenticate, both answered as the token endpoint would.
-   */
   static success() {
     return new Response(null, { status: 200, headers: OAuthErrors.noStore });
   }

package/server/oauth/OAuthToken.ts

@@ -12,10 +12,7 @@ export interface OAuthTokenSuccess {
 }
 
 export class OAuthToken {
-  /**
-   * RFC 6749 §4.1.3 and §6: the token endpoint speaks form encoding only, and a client authenticates through the
-   * `Authorization` header or the body, never both — two credentials on one request is a request nobody can audit.
-   */
+  
   static async parse(req: Request): Promise<OAuthTokenParseResult> {
     const type = req.headers.get("content-type")?.toLowerCase() ?? "";
     if (!type.startsWith("application/x-www-form-urlencoded"))
@@ -51,11 +48,6 @@ export class OAuthToken {
     return OAuthToken.#fail("unsupported_grant_type", "Only authorization_code and refresh_token are supported.");
   }
 
-  /**
-   * Whether the credential presented is this client's. A public client has none to present, and a secret it sends
-   * anyway is ignored rather than refused — OAuth 2.1 §2.3 lets a public client keep naming itself. A confidential
-   * client must present its secret, compared as hashes in constant time.
-   */
   static authenticate(
     client: OAuthClientRecord,
     credential: OAuthClientCredential,
@@ -82,14 +74,11 @@ export class OAuthToken {
     );
   }
 
-  /**
-   * `null` when both channels carried a credential. RFC 6749 §2.3.1 form-encodes the two halves of the Basic pair.
-   * Shared with the revocation endpoint, which RFC 7009 §2.1 authenticates the same way.
-   */
+  /** `null` when both channels carried a credential. Basic halves are form-encoded (RFC 6749 §2.3.1). */
   static credentialOf(req: Request, form: URLSearchParams): OAuthClientCredential | null {
     const header = req.headers.get("authorization");
     const bodySecret = form.get("client_secret") ?? undefined;
-    if (header?.startsWith("Basic ")) {
+    if (header && /^Basic /i.test(header)) {
       if (bodySecret !== undefined) return null;
       const decoded = Buffer.from(header.slice("Basic ".length).trim(), "base64").toString("utf8");
       const separator = decoded.indexOf(":");

package/server/oauth/oauthTypes.ts

@@ -1,6 +1,6 @@
 export type OAuthClientAuthMethod = "none" | "client_secret_post" | "client_secret_basic";
 
-/** How a client came to be known: declared in the app's option, registered over RFC 7591, or read off its `client_id` URL. */
+/** Declared in the app's option, registered over RFC 7591, or read off its `client_id` URL. */
 export type OAuthClientSource = "static" | "dynamic" | "metadataDocument";
 
 export interface OAuthClientRecord {
@@ -13,7 +13,6 @@ export interface OAuthClientRecord {
   source: OAuthClientSource;
 }
 
-/** The metadata a registration request carries, before the server assigns an identifier to it. */
 export type OAuthClientMetadata = Pick<
   OAuthClientRecord,
   "clientName" | "redirectUris" | "grantTypes" | "tokenEndpointAuthMethod"

package/server/ops/ageEncryption.ts

@@ -0,0 +1,317 @@
+import {
+  createHmac,
+  createPrivateKey,
+  createPublicKey,
+  diffieHellman,
+  generateKeyPairSync,
+  hkdfSync,
+  type KeyObject,
+  randomBytes,
+  timingSafeEqual,
+} from "node:crypto";
+import { Transform } from "node:stream";
+import type { SnapshotDecryptor } from "./snapshotRestore";
+import type { SnapshotEncryption } from "./snapshotTypes";
+import type { SnapshotEncryptor } from "./sqliteSnapshot";
+
+type Aead = (
+  key: Uint8Array,
+  nonce: Uint8Array,
+) => {
+  encrypt(data: Uint8Array): Uint8Array;
+  decrypt(data: Uint8Array): Uint8Array;
+};
+
+export class AgeEncryption {
+  static readonly intro = "age-encryption.org/v1";
+  static readonly chunkSize = 64 * 1024;
+  static readonly tagSize = 16;
+  static readonly #x25519Info = "age-encryption.org/v1/X25519";
+  static readonly #spkiPrefix = Buffer.from("302a300506032b656e032100", "hex");
+  static readonly #pkcs8Prefix = Buffer.from("302e020100300506032b656e04220420", "hex");
+  static readonly #bech32Charset = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+
+  static async encryptor(recipients: string[]): Promise<SnapshotEncryptor> {
+    const aead = await AgeEncryption.#aead();
+    const keys = recipients.map((recipient) => AgeEncryption.parseRecipient(recipient));
+    const encryption: SnapshotEncryption = { format: "age", recipients };
+    return { encryption, extension: ".age", transform: () => AgeEncryption.#encryptStream(aead, keys) };
+  }
+
+  static async decryptor(identities: string[]): Promise<SnapshotDecryptor> {
+    const aead = await AgeEncryption.#aead();
+    const keys = identities.map((identity) => AgeEncryption.parseIdentity(identity));
+    return { transform: () => AgeEncryption.#decryptStream(aead, keys) };
+  }
+
+  static async fromEnv(): Promise<SnapshotEncryptor | null> {
+    const recipients = (process.env.AKAN_BACKUP_RECIPIENT ?? "")
+      .split(",")
+      .map((value) => value.trim())
+      .filter(Boolean);
+    return recipients.length ? await AgeEncryption.encryptor(recipients) : null;
+  }
+
+  static identitiesIn(text: string) {
+    return text
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.startsWith("AGE-SECRET-KEY-1"));
+  }
+
+  static generateIdentity() {
+    const { privateKey, publicKey } = generateKeyPairSync("x25519");
+    const secret = privateKey.export({ format: "der", type: "pkcs8" }).subarray(-32);
+    const pub = publicKey.export({ format: "der", type: "spki" }).subarray(-32);
+    return {
+      identity: AgeEncryption.#bech32Encode("age-secret-key-", secret).toUpperCase(),
+      recipient: AgeEncryption.#bech32Encode("age", pub),
+    };
+  }
+
+  static parseRecipient(recipient: string): KeyObject {
+    const bytes = AgeEncryption.#bech32Decode(recipient.trim(), "age");
+    return createPublicKey({ key: Buffer.concat([AgeEncryption.#spkiPrefix, bytes]), format: "der", type: "spki" });
+  }
+
+  static parseIdentity(identity: string): KeyObject {
+    const bytes = AgeEncryption.#bech32Decode(identity.trim().toLowerCase(), "age-secret-key-");
+    return createPrivateKey({ key: Buffer.concat([AgeEncryption.#pkcs8Prefix, bytes]), format: "der", type: "pkcs8" });
+  }
+
+  static async #aead(): Promise<Aead> {
+    const { chacha20poly1305 } = await import("@noble/ciphers/chacha.js");
+    return (key, nonce) => chacha20poly1305(key, nonce);
+  }
+
+  static #header(aead: Aead, recipients: KeyObject[], fileKey: Buffer) {
+    const lines = [AgeEncryption.intro];
+    for (const recipient of recipients) {
+      const ephemeral = generateKeyPairSync("x25519");
+      const share = ephemeral.publicKey.export({ format: "der", type: "spki" }).subarray(-32);
+      const recipientRaw = recipient.export({ format: "der", type: "spki" }).subarray(-32);
+      const shared = diffieHellman({ privateKey: ephemeral.privateKey, publicKey: recipient });
+      const wrapKey = AgeEncryption.#hkdf(shared, Buffer.concat([share, recipientRaw]), AgeEncryption.#x25519Info);
+      const body = aead(wrapKey, new Uint8Array(12)).encrypt(fileKey);
+      lines.push(`-> X25519 ${AgeEncryption.#b64(share)}`, ...AgeEncryption.#wrap(AgeEncryption.#b64(body)));
+    }
+    const beforeMac = `${lines.join("\n")}\n---`;
+    const mac = createHmac("sha256", AgeEncryption.#hkdf(fileKey, Buffer.alloc(0), "header"))
+      .update(beforeMac)
+      .digest();
+    return Buffer.from(`${beforeMac} ${AgeEncryption.#b64(mac)}\n`);
+  }
+
+  static #encryptStream(aead: Aead, recipients: KeyObject[]) {
+    const fileKey = randomBytes(16);
+    const payloadNonce = randomBytes(16);
+    const streamKey = AgeEncryption.#hkdf(fileKey, payloadNonce, "payload");
+    let pending: Buffer = Buffer.alloc(0);
+    let counter = 0n;
+    let started = false;
+    const seal = (chunk: Buffer, last: boolean) =>
+      aead(streamKey, AgeEncryption.#chunkNonce(counter++, last)).encrypt(chunk);
+    return new Transform({
+      transform(chunk: Buffer, _encoding, callback) {
+        if (!started) {
+          this.push(AgeEncryption.#header(aead, recipients, fileKey));
+          this.push(payloadNonce);
+          started = true;
+        }
+        pending = pending.length ? Buffer.concat([pending, chunk]) : chunk;
+        
+        while (pending.length > AgeEncryption.chunkSize) {
+          this.push(seal(pending.subarray(0, AgeEncryption.chunkSize), false));
+          pending = pending.subarray(AgeEncryption.chunkSize);
+        }
+        callback();
+      },
+      flush(callback) {
+        if (!started) {
+          this.push(AgeEncryption.#header(aead, recipients, fileKey));
+          this.push(payloadNonce);
+        }
+        this.push(seal(pending, true));
+        callback();
+      },
+    });
+  }
+
+  static #decryptStream(aead: Aead, identities: KeyObject[]) {
+    let buffered: Buffer = Buffer.alloc(0);
+    let streamKey: Uint8Array | null = null;
+    let counter = 0n;
+    const sealedSize = AgeEncryption.chunkSize + AgeEncryption.tagSize;
+    const open = (chunk: Buffer, last: boolean) => {
+      if (!streamKey) throw new Error("age payload before header");
+      return aead(streamKey, AgeEncryption.#chunkNonce(counter++, last)).decrypt(chunk);
+    };
+    return new Transform({
+      transform(chunk: Buffer, _encoding, callback) {
+        try {
+          buffered = buffered.length ? Buffer.concat([buffered, chunk]) : chunk;
+          if (!streamKey) {
+            const parsed = AgeEncryption.#readHeader(aead, buffered, identities);
+            if (!parsed) return callback();
+            streamKey = parsed.streamKey;
+            buffered = buffered.subarray(parsed.consumed);
+          }
+          while (buffered.length > sealedSize) {
+            this.push(open(buffered.subarray(0, sealedSize), false));
+            buffered = buffered.subarray(sealedSize);
+          }
+          callback();
+        } catch (error) {
+          callback(error as Error);
+        }
+      },
+      flush(callback) {
+        try {
+          if (!streamKey) throw new Error("truncated age header");
+          const plain = open(buffered, true);
+          if (plain.length === 0 && counter > 1n) throw new Error("age payload ends with an empty chunk");
+          this.push(plain);
+          callback();
+        } catch (error) {
+          callback(error as Error);
+        }
+      },
+    });
+  }
+
+  static #readHeader(aead: Aead, data: Buffer, identities: KeyObject[]) {
+    const macAt = data.indexOf("\n--- ");
+    if (macAt < 0) return null;
+    const macEnd = data.indexOf("\n", macAt + 1);
+    if (macEnd < 0 || data.length < macEnd + 1 + 16) return null;
+    const text = data.subarray(0, macAt).toString("utf8");
+    const lines = text.split("\n");
+    if (lines[0] !== AgeEncryption.intro) throw new Error("not an age v1 file");
+    const stanzas: { args: string[]; body: Buffer }[] = [];
+    for (let idx = 1; idx < lines.length; ) {
+      const line = lines[idx++] ?? "";
+      if (!line.startsWith("-> ")) throw new Error("malformed age stanza");
+      let body = "";
+      for (;;) {
+        const bodyLine = lines[idx++] ?? "";
+        body += bodyLine;
+        if (bodyLine.length < 64) break;
+      }
+      stanzas.push({ args: line.slice(3).split(" "), body: Buffer.from(body, "base64") });
+    }
+    const fileKey = AgeEncryption.#unwrapFileKey(aead, stanzas, identities);
+    const macText = data.subarray(0, macAt + 4).toString("utf8");
+    const mac = Buffer.from(data.subarray(macAt + 5, macEnd).toString("utf8"), "base64");
+    const expected = createHmac("sha256", AgeEncryption.#hkdf(fileKey, Buffer.alloc(0), "header"))
+      .update(macText)
+      .digest();
+    if (mac.length !== expected.length || !timingSafeEqual(mac, expected)) throw new Error("age header MAC mismatch");
+    const nonce = data.subarray(macEnd + 1, macEnd + 17);
+    return { streamKey: AgeEncryption.#hkdf(fileKey, nonce, "payload"), consumed: macEnd + 17 };
+  }
+
+  static #unwrapFileKey(aead: Aead, stanzas: { args: string[]; body: Buffer }[], identities: KeyObject[]) {
+    for (const identity of identities) {
+      const ourPublic = createPublicKey(identity).export({ format: "der", type: "spki" }).subarray(-32);
+      for (const { args, body } of stanzas) {
+        if (args[0] !== "X25519" || !args[1]) continue;
+        const share = Buffer.from(args[1], "base64");
+        const peer = createPublicKey({
+          key: Buffer.concat([AgeEncryption.#spkiPrefix, share]),
+          format: "der",
+          type: "spki",
+        });
+        const shared = diffieHellman({ privateKey: identity, publicKey: peer });
+        if (shared.every((byte) => byte === 0)) continue;
+        const wrapKey = AgeEncryption.#hkdf(shared, Buffer.concat([share, ourPublic]), AgeEncryption.#x25519Info);
+        try {
+          return Buffer.from(aead(wrapKey, new Uint8Array(12)).decrypt(body));
+        } catch {
+        }
+      }
+    }
+    throw new Error("no identity matches any age recipient in this file");
+  }
+
+  static #chunkNonce(counter: bigint, last: boolean) {
+    const nonce = new Uint8Array(12);
+    let value = counter;
+    for (let idx = 10; idx >= 0; idx--) {
+      nonce[idx] = Number(value & 0xffn);
+      value >>= 8n;
+    }
+    nonce[11] = last ? 1 : 0;
+    return nonce;
+  }
+
+  static #hkdf(ikm: Uint8Array, salt: Uint8Array, info: string) {
+    return new Uint8Array(hkdfSync("sha256", ikm, salt, info, 32));
+  }
+
+  static #b64(bytes: Uint8Array) {
+    return Buffer.from(bytes).toString("base64").replace(/=+$/, "");
+  }
+
+  static #wrap(value: string) {
+    const lines: string[] = [];
+    for (let idx = 0; idx < value.length; idx += 64) lines.push(value.slice(idx, idx + 64));
+    
+    if (value.length % 64 === 0) lines.push("");
+    return lines;
+  }
+
+  static #bech32Polymod(values: number[]) {
+    const generators = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+    let chk = 1;
+    for (const value of values) {
+      const top = chk >>> 25;
+      chk = ((chk & 0x1ffffff) << 5) ^ value;
+      for (let idx = 0; idx < 5; idx++) if ((top >>> idx) & 1) chk ^= generators[idx] ?? 0;
+    }
+    return chk;
+  }
+
+  static #hrpExpand(hrp: string) {
+    const codes = [...hrp].map((char) => char.charCodeAt(0));
+    return [...codes.map((code) => code >>> 5), 0, ...codes.map((code) => code & 31)];
+  }
+
+  static #convertBits(data: Iterable<number>, from: number, to: number, pad: boolean) {
+    let acc = 0;
+    let bits = 0;
+    const out: number[] = [];
+    const max = (1 << to) - 1;
+    for (const value of data) {
+      acc = (acc << from) | value;
+      bits += from;
+      while (bits >= to) {
+        bits -= to;
+        out.push((acc >>> bits) & max);
+      }
+    }
+    if (pad && bits > 0) out.push((acc << (to - bits)) & max);
+    else if (!pad && (bits >= from || (acc << (to - bits)) & max)) throw new Error("invalid bech32 padding");
+    return out;
+  }
+
+  static #bech32Encode(hrp: string, bytes: Uint8Array) {
+    const data = AgeEncryption.#convertBits(bytes, 8, 5, true);
+    const polymod = AgeEncryption.#bech32Polymod([...AgeEncryption.#hrpExpand(hrp), ...data, 0, 0, 0, 0, 0, 0]) ^ 1;
+    const checksum = Array.from({ length: 6 }, (_, idx) => (polymod >>> (5 * (5 - idx))) & 31);
+    return `${hrp}1${[...data, ...checksum].map((value) => AgeEncryption.#bech32Charset[value]).join("")}`;
+  }
+
+  static #bech32Decode(value: string, expectedHrp: string) {
+    const lower = value.toLowerCase();
+    const separator = lower.lastIndexOf("1");
+    const hrp = lower.slice(0, separator);
+    if (separator < 1 || hrp !== expectedHrp) throw new Error(`expected an ${expectedHrp}1… key`);
+    const data = [...lower.slice(separator + 1)].map((char) => AgeEncryption.#bech32Charset.indexOf(char));
+    if (data.length < 6 || data.some((code) => code < 0)) throw new Error("invalid bech32 characters");
+    if (AgeEncryption.#bech32Polymod([...AgeEncryption.#hrpExpand(hrp), ...data]) !== 1)
+      throw new Error("invalid bech32 checksum");
+    const bytes = Buffer.from(AgeEncryption.#convertBits(data.slice(0, -6), 5, 8, false));
+    if (bytes.length !== 32) throw new Error("age keys are 32 bytes");
+    return bytes;
+  }
+}