@retinue/agentkit 0.1.0 → 0.3.0

package/dist/audio/index.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Hearing and speaking — REQ-062 (#257), task #258, Part 2.
+ *
+ * Two ports, because the two acts are genuinely separate and a deployment will often want one and not the
+ * other: transcription turns audio into text so a text-only model can read it, and speech turns text into
+ * audio so an interface can play it.
+ *
+ * ## Why ports rather than tools that call an API
+ *
+ * The same reason `tools-search` supplies providers instead of tools. Whisper, Deepgram, AssemblyAI and a
+ * self-hosted `whisper.cpp` are four *values*, not four sets of tools — and which one a deployment uses is a
+ * decision about cost, residency and latency that a model should never spend a tool call discovering.
+ *
+ * It also keeps AC-2's real case honest: *"so a deployment can use a model that does not accept audio
+ * natively"*. Most models do not. Transcribing first and sending text is how audio reaches them at all, and
+ * that path has to exist independently of any one provider.
+ *
+ * ## Bounds are enforced before the upload, not after
+ *
+ * AC-4 says so and it is the part most easily got wrong: the natural implementation reads the file, stores it,
+ * and then checks. A rejected 200MB recording must not be stored first — it costs the blob write, the
+ * retention obligation and the deletion, all for something that was never going to be accepted.
+ *
+ * So the check takes a *declared* size and media type and answers before any bytes move. `assertWithinBounds`
+ * is the function a caller runs at the boundary; nothing here reads a file to find out whether it may.
+ *
+ * ## Duration is bounded too, and it cannot be checked from the size
+ *
+ * A byte ceiling is not a duration ceiling: an hour of 8kbps speech is smaller than a minute of uncompressed
+ * WAV. Both matter for different reasons — bytes bound the storage and the upload, seconds bound the *cost*,
+ * because audio is billed per second. A deployment that bounded only bytes would have an unbounded bill.
+ *
+ * Duration is therefore checked where it becomes known: declared by the caller if it knows, and reported by
+ * the provider afterwards. `assertWithinBounds` refuses a declared duration over the ceiling before the call;
+ * `TranscriptionResult.durationSeconds` is what usage is charged on.
+ */
+import { type PlatformError } from "../core/errors.js";
+/**
+ * The media types accepted, and it is a list rather than `audio/*` on purpose.
+ *
+ * A provider rejects an unknown container with a message about the request, not about the format, so the
+ * useful refusal happens here. Every entry is one that the shipped adapters actually accept.
+ */
+export declare const AUDIO_MEDIA_TYPES: readonly ["audio/mpeg", "audio/mp4", "audio/wav", "audio/webm", "audio/ogg", "audio/flac", "audio/x-m4a"];
+export type AudioMediaType = (typeof AUDIO_MEDIA_TYPES)[number];
+export declare const isAudioMediaType: (mediaType: string) => mediaType is AudioMediaType;
+/**
+ * 25MB, which is where every hosted transcription API this could target draws its own line.
+ *
+ * Matching the provider's limit rather than inventing a smaller one: a deployment that wants less sets its
+ * own, and a ceiling *above* the provider's would just move the failure later and make it theirs to explain.
+ */
+export declare const MAX_AUDIO_BYTES: number;
+/**
+ * One hour.
+ *
+ * The number is about cost rather than capability. At a typical per-second rate an hour is already a
+ * noticeable charge for a single tool call, and a run that transcribes a six-hour recording by accident is the
+ * kind of bill nobody notices until the invoice.
+ */
+export declare const MAX_AUDIO_SECONDS = 3600;
+/**
+ * The transcript ceiling — AC-5.
+ *
+ * An hour of speech is roughly 9,000 words, which fits. This bounds the *pathological* case: a provider that
+ * returns a repeated hallucination on silence, which is a known Whisper failure mode and produces megabytes of
+ * one phrase. Truncation is reported, never silent — a shortened transcript that claimed to be complete would
+ * make the model summarise a fragment as if it were the whole recording.
+ */
+export declare const MAX_TRANSCRIPT_CHARS = 100000;
+/** What speech generation may be asked to say. Bounds the cost the same way the audio ceiling does. */
+export declare const MAX_SPEECH_CHARS = 4000;
+export type AudioBounds = {
+    readonly maxBytes?: number;
+    readonly maxSeconds?: number;
+};
+export declare class AudioRejected extends Error {
+    readonly code: "invalid_input";
+}
+/**
+ * Refuses before anything is stored or sent — AC-4.
+ *
+ * Takes what a caller knows *without reading the file*: the declared byte length and media type from the
+ * upload, and a duration if the client measured one. Deliberately not given the bytes: a function that
+ * received them would invite reading them, and the whole point is to answer before they move.
+ */
+export declare const assertWithinBounds: (input: {
+    readonly byteSize: number;
+    readonly mediaType: string;
+    readonly durationSeconds?: number;
+}, bounds?: AudioBounds) => void;
+/** A transcript, bounded, with the truncation reported rather than hidden. */
+export type TranscriptionResult = {
+    readonly text: string;
+    /**
+     * What usage is charged on — AC-8. Reported by the provider, because only it knows.
+     *
+     * A provider that does not report it leaves this absent rather than guessing, and the recorder then charges
+     * nothing for the audio. That under-bills, which is why the shipped adapter asks for a response format that
+     * includes it.
+     */
+    readonly durationSeconds?: number;
+    readonly truncated: boolean;
+    /** The provider's own language detection, when it offers one. Not a translation — see the REQ's scope. */
+    readonly language?: string;
+};
+export type TranscriptionRequest = {
+    readonly audio: Uint8Array;
+    readonly mediaType: string;
+    readonly filename?: string;
+    /** A hint, not an instruction. A provider free to detect is usually better at it than a caller guessing. */
+    readonly languageHint?: string;
+    readonly maxTranscriptChars?: number;
+};
+export interface TranscriptionProvider {
+    readonly id: string;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+}
+export type SpeechRequest = {
+    readonly text: string;
+    /** The provider's own voice identifier. Opaque here: naming a fixed set would date immediately. */
+    readonly voice?: string;
+    readonly format?: "mp3" | "wav" | "opus" | "flac";
+};
+export type SpeechResult = {
+    readonly audio: Uint8Array;
+    readonly mediaType: string;
+    /** Absent when the provider does not report it. Charged on when present. */
+    readonly durationSeconds?: number;
+};
+export interface SpeechProvider {
+    readonly id: string;
+    speak(request: SpeechRequest): Promise<SpeechResult>;
+}
+/** Bounds a transcript and says whether it had to. */
+export declare const boundTranscript: (text: string, maxChars?: number) => {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * A provider failure, in the platform's vocabulary — AC-5.
+ *
+ * Deliberately the same shape and the same distinctions as `describeFetchFailure`: 429 and 5xx retryable,
+ * unreachable `provider_unavailable`, everything else terminal. A second vocabulary for audio would mean the
+ * runtime's retry logic treated a transcription rate limit differently from a scrape rate limit for no reason
+ * anybody chose.
+ */
+export declare const describeAudioFailure: (error: unknown, provider: string) => PlatformError;
+/** Throws the classified failure, for a caller that would rather not branch. */
+export declare const failAudio: (error: unknown, provider: string) => never;
+//# sourceMappingURL=index.d.ts.map

package/dist/audio/index.js

@@ -0,0 +1,183 @@
+/**
+ * Hearing and speaking — REQ-062 (#257), task #258, Part 2.
+ *
+ * Two ports, because the two acts are genuinely separate and a deployment will often want one and not the
+ * other: transcription turns audio into text so a text-only model can read it, and speech turns text into
+ * audio so an interface can play it.
+ *
+ * ## Why ports rather than tools that call an API
+ *
+ * The same reason `tools-search` supplies providers instead of tools. Whisper, Deepgram, AssemblyAI and a
+ * self-hosted `whisper.cpp` are four *values*, not four sets of tools — and which one a deployment uses is a
+ * decision about cost, residency and latency that a model should never spend a tool call discovering.
+ *
+ * It also keeps AC-2's real case honest: *"so a deployment can use a model that does not accept audio
+ * natively"*. Most models do not. Transcribing first and sending text is how audio reaches them at all, and
+ * that path has to exist independently of any one provider.
+ *
+ * ## Bounds are enforced before the upload, not after
+ *
+ * AC-4 says so and it is the part most easily got wrong: the natural implementation reads the file, stores it,
+ * and then checks. A rejected 200MB recording must not be stored first — it costs the blob write, the
+ * retention obligation and the deletion, all for something that was never going to be accepted.
+ *
+ * So the check takes a *declared* size and media type and answers before any bytes move. `assertWithinBounds`
+ * is the function a caller runs at the boundary; nothing here reads a file to find out whether it may.
+ *
+ * ## Duration is bounded too, and it cannot be checked from the size
+ *
+ * A byte ceiling is not a duration ceiling: an hour of 8kbps speech is smaller than a minute of uncompressed
+ * WAV. Both matter for different reasons — bytes bound the storage and the upload, seconds bound the *cost*,
+ * because audio is billed per second. A deployment that bounded only bytes would have an unbounded bill.
+ *
+ * Duration is therefore checked where it becomes known: declared by the caller if it knows, and reported by
+ * the provider afterwards. `assertWithinBounds` refuses a declared duration over the ceiling before the call;
+ * `TranscriptionResult.durationSeconds` is what usage is charged on.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+/**
+ * The media types accepted, and it is a list rather than `audio/*` on purpose.
+ *
+ * A provider rejects an unknown container with a message about the request, not about the format, so the
+ * useful refusal happens here. Every entry is one that the shipped adapters actually accept.
+ */
+export const AUDIO_MEDIA_TYPES = [
+    "audio/mpeg",
+    "audio/mp4",
+    "audio/wav",
+    "audio/webm",
+    "audio/ogg",
+    "audio/flac",
+    "audio/x-m4a",
+];
+export const isAudioMediaType = (mediaType) => AUDIO_MEDIA_TYPES.includes(mediaType.split(";")[0]?.trim().toLowerCase() ?? "");
+/**
+ * 25MB, which is where every hosted transcription API this could target draws its own line.
+ *
+ * Matching the provider's limit rather than inventing a smaller one: a deployment that wants less sets its
+ * own, and a ceiling *above* the provider's would just move the failure later and make it theirs to explain.
+ */
+export const MAX_AUDIO_BYTES = 25 * 1024 * 1024;
+/**
+ * One hour.
+ *
+ * The number is about cost rather than capability. At a typical per-second rate an hour is already a
+ * noticeable charge for a single tool call, and a run that transcribes a six-hour recording by accident is the
+ * kind of bill nobody notices until the invoice.
+ */
+export const MAX_AUDIO_SECONDS = 3_600;
+/**
+ * The transcript ceiling — AC-5.
+ *
+ * An hour of speech is roughly 9,000 words, which fits. This bounds the *pathological* case: a provider that
+ * returns a repeated hallucination on silence, which is a known Whisper failure mode and produces megabytes of
+ * one phrase. Truncation is reported, never silent — a shortened transcript that claimed to be complete would
+ * make the model summarise a fragment as if it were the whole recording.
+ */
+export const MAX_TRANSCRIPT_CHARS = 100_000;
+/** What speech generation may be asked to say. Bounds the cost the same way the audio ceiling does. */
+export const MAX_SPEECH_CHARS = 4_000;
+export class AudioRejected extends Error {
+    code = "invalid_input";
+}
+/**
+ * Refuses before anything is stored or sent — AC-4.
+ *
+ * Takes what a caller knows *without reading the file*: the declared byte length and media type from the
+ * upload, and a duration if the client measured one. Deliberately not given the bytes: a function that
+ * received them would invite reading them, and the whole point is to answer before they move.
+ */
+export const assertWithinBounds = (input, bounds = {}) => {
+    const maxBytes = bounds.maxBytes ?? MAX_AUDIO_BYTES;
+    const maxSeconds = bounds.maxSeconds ?? MAX_AUDIO_SECONDS;
+    if (!isAudioMediaType(input.mediaType)) {
+        throw new AudioRejected(`${input.mediaType} is not an audio format this deployment accepts. Accepted: ` +
+            `${AUDIO_MEDIA_TYPES.join(", ")}.`);
+    }
+    if (!Number.isFinite(input.byteSize) || input.byteSize <= 0) {
+        throw new AudioRejected("An audio attachment needs a declared size, and it must be greater than zero.");
+    }
+    if (input.byteSize > maxBytes) {
+        throw new AudioRejected(`That recording is ${Math.round(input.byteSize / 1024 / 1024)}MB and the limit is ` +
+            `${Math.round(maxBytes / 1024 / 1024)}MB. Refused before upload — nothing was stored.`);
+    }
+    /**
+     * Duration only when the caller declared one.
+     *
+     * Absent is not an error: a browser knows the duration of a recording it just made and a server receiving a
+     * file often does not, and demanding it would mean either refusing legitimate uploads or reading the file to
+     * find out — which is the thing this function exists to avoid.
+     */
+    if (input.durationSeconds !== undefined && input.durationSeconds > maxSeconds) {
+        throw new AudioRejected(`That recording is ${Math.round(input.durationSeconds / 60)} minutes and the limit is ` +
+            `${Math.round(maxSeconds / 60)}. Refused before upload — nothing was stored.`);
+    }
+};
+/** Bounds a transcript and says whether it had to. */
+export const boundTranscript = (text, maxChars = MAX_TRANSCRIPT_CHARS) => {
+    if (text.length <= maxChars)
+        return { text, truncated: false };
+    /**
+     * Cut at a word boundary when there is one nearby.
+     *
+     * A transcript sliced mid-word reads as a transcription error rather than as a truncation, and a model
+     * summarising it will occasionally treat the fragment as a real word. The 200-character window is small
+     * enough that the ceiling still means what it says.
+     */
+    const hard = text.slice(0, maxChars);
+    const lastSpace = hard.lastIndexOf(" ");
+    /**
+     * `lastSpace > 0` matters, and its absence was a bug the tests caught.
+     *
+     * `lastIndexOf` returns `-1` when there is no space at all — and `-1 > maxChars - 200` is *true* for any
+     * ceiling under 200, so the original condition sliced to `-1` and silently dropped the final character of
+     * every space-free transcript. A one-character loss that no assertion about truncation would notice.
+     */
+    const useBoundary = lastSpace > 0 && lastSpace > maxChars - 200;
+    return { text: useBoundary ? hard.slice(0, lastSpace) : hard, truncated: true };
+};
+/**
+ * A provider failure, in the platform's vocabulary — AC-5.
+ *
+ * Deliberately the same shape and the same distinctions as `describeFetchFailure`: 429 and 5xx retryable,
+ * unreachable `provider_unavailable`, everything else terminal. A second vocabulary for audio would mean the
+ * runtime's retry logic treated a transcription rate limit differently from a scrape rate limit for no reason
+ * anybody chose.
+ */
+export const describeAudioFailure = (error, provider) => {
+    if (error instanceof AudioRejected) {
+        return { code: "invalid_input", message: error.message, retryable: false };
+    }
+    const status = error.status;
+    const message = error instanceof Error ? error.message : String(error);
+    if (status === 429) {
+        return { code: "rate_limited", message: `${provider} is rate limiting: ${message}`, retryable: true };
+    }
+    if (status === 413) {
+        // Not retryable, and worth its own arm: the file is too large and will be next time too.
+        return {
+            code: "invalid_input",
+            message: `${provider} refused the recording as too large: ${message}`,
+            retryable: false,
+        };
+    }
+    if (status === 401 || status === 403) {
+        return {
+            code: "unauthorized",
+            message: `${provider} refused the credential: ${message}. Retrying will not help.`,
+            retryable: false,
+        };
+    }
+    if (status !== undefined && status >= 500) {
+        return { code: "provider_unavailable", message: `${provider} returned ${status}: ${message}`, retryable: true };
+    }
+    if (/timed out|etimedout|abort|fetch failed|econnrefused|enotfound/i.test(message)) {
+        return { code: "provider_unavailable", message: `${provider} could not be reached: ${message}`, retryable: true };
+    }
+    return { code: "provider_error", message: `${provider} could not process the audio: ${message}`, retryable: false };
+};
+/** Throws the classified failure, for a caller that would rather not branch. */
+export const failAudio = (error, provider) => {
+    throw new AgentPlatformError(describeAudioFailure(error, provider));
+};
+//# sourceMappingURL=index.js.map

package/dist/capabilities/index.d.ts

@@ -34,7 +34,7 @@
  * which auto-approves a stated set of effects, and is auditable afterwards where a flag leaves no record. The
  * difference is between "nobody had to approve this" and "we cannot tell whether anyone should have".
  */
-export declare const CAPABILITIES: readonly ["history", "memory", "compaction", "citations", "questions", "skills", "mcp", "usage"];
+export declare const CAPABILITIES: readonly ["history", "memory", "compaction", "citations", "questions", "skills", "mcp", "usage", "guardrails", "shell"];
 export type Capability = (typeof CAPABILITIES)[number];
 export type CapabilityState = "on" | "off";
 export type CapabilityMap = Readonly<Record<Capability, CapabilityState>>;
@@ -62,6 +62,8 @@ export declare const PROFILES: {
         readonly skills: "on";
         readonly mcp: "off";
         readonly usage: "on";
+        readonly guardrails: "off";
+        readonly shell: "off";
     };
     /**
      * A headless automation: no conversation, no person, no recall.
@@ -78,6 +80,8 @@ export declare const PROFILES: {
         readonly skills: "off";
         readonly mcp: "off";
         readonly usage: "on";
+        readonly guardrails: "off";
+        readonly shell: "off";
     };
 };
 export type ProfileName = keyof typeof PROFILES;

package/dist/capabilities/index.js

@@ -44,6 +44,8 @@ export const CAPABILITIES = [
     "skills",
     "mcp",
     "usage",
+    "guardrails",
+    "shell",
 ];
 /**
  * What each capability cannot work without, by the name a host wires it under.
@@ -62,6 +64,18 @@ export const CAPABILITY_REQUIRES = {
     skills: ["skills"],
     mcp: ["mcpConnections", "mcpClient"],
     usage: ["usage"],
+    // A guardrail set, supplied by the host. Declaring the capability without wiring one is refused at
+    // construction — which is the point: "guardrails: on" must mean a check exists, not that somebody intended one.
+    guardrails: ["guardrails"],
+    /**
+     * A sandbox for `shell_exec` — REQ-047 (#206), task #215.
+     *
+     * The only capability whose *absence* is a security property rather than a missing feature. `shell_exec` is
+     * arbitrary code execution with a natural-language trigger, so it takes two switches: a sandbox wired, and this
+     * declared. Declaring it with no sandbox is refused at construction, and wiring a sandbox without declaring it
+     * leaves the tool present and refusing — which is the safe direction of the two.
+     */
+    shell: ["sandbox"],
 };
 const OFF = Object.freeze(Object.fromEntries(CAPABILITIES.map((c) => [c, "off"])));
 /**
@@ -81,6 +95,13 @@ export const PROFILES = {
         skills: "on",
         mcp: "off",
         usage: "on",
+        // Off in both profiles, deliberately. A guardrail set is the host's — and a profile that turned this on
+        // would be a profile that refuses to construct until somebody supplies one, which is a poor default for a
+        // named starting point.
+        guardrails: "off",
+        // Off in both profiles, and this one should never be otherwise: no named starting point gets to decide that
+        // an application can run shell commands.
+        shell: "off",
     },
     /**
      * A headless automation: no conversation, no person, no recall.
@@ -97,6 +118,8 @@ export const PROFILES = {
         skills: "off",
         mcp: "off",
         usage: "on",
+        guardrails: "off",
+        shell: "off",
     },
 };
 /** A profile as a plain map, so a caller can read a default before adopting it. */

package/dist/capabilities/runtime.d.ts

@@ -18,6 +18,7 @@
  * capability. Not a function a caller must remember to call first: the ones who forget are exactly the six
  * defects this module exists for. Every consumer of a store goes through the same property.
  */
+import type { Guardrail } from "../guardrails/index.js";
 import type { RunEventLog } from "../core/events.js";
 import type { InteractionStore, MessageStore, RunStore, SkillStore, ThreadSummaryStore, UsageStore } from "../persistence/index.js";
 import type { PrincipalMemoryStore } from "../principal-memory/index.js";
@@ -56,6 +57,13 @@ export type RuntimeStores = {
 export type RuntimeServices = {
     readonly summarizer?: ThreadSummarizer;
     readonly mcpClient?: McpClient;
+    /**
+     * Ordered, and the order is the host's — REQ-046 (#205), AC-7.
+     *
+     * An array rather than a record, because composition order decides the outcome when two guardrails both
+     * redact, and a record's key order is an implementation detail that changes when somebody reformats a config.
+     */
+    readonly guardrails?: readonly Guardrail[];
 };
 export type CreateRuntimeInput = {
     readonly profile?: ProfileName;

package/dist/connections/cipher.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `SecretCipher` — encryption at rest for third-party credentials, REQ-063 (#259), task #261.
+ *
+ * `docs/21`'s Connections section sets the requirement, and it is precise enough to decide the design:
+ *
+ * > encryption at rest with **a key the application database cannot decrypt on its own**
+ *
+ * That sentence rules out the two obvious implementations.
+ *
+ * ## Why not `pgcrypto`
+ *
+ * `pgp_sym_encrypt(data, key)` needs the key passed into each query. A key stored in the same database as the
+ * ciphertext satisfies nothing — it protects against a stolen backup and nothing else, and the sentence above
+ * rules it out by name. A key passed as a SQL literal is worse: it can land in `pg_stat_statements`, in the
+ * server log and in a slow-query log, which are three places nobody thinks of as credential stores.
+ *
+ * `pgsodium` and its transparent column encryption are deprecated; do not build on them.
+ *
+ * ## Why not Supabase Vault alone
+ *
+ * Supabase Vault is genuinely good — libsodium, and a root key held outside the database, so it satisfies the
+ * requirement. It is also available only on Supabase. Building on it would leave the Postgres and in-memory
+ * adapters storing plaintext, so the conformance suite would be asserting *different guarantees per adapter* —
+ * which is the one thing a conformance suite must never do.
+ *
+ * ## So: encrypt in the application, behind a seam
+ *
+ * The store holds an opaque ciphertext blob and knows nothing about how it was produced. Every adapter family
+ * gets the identical property, no key passes through SQL, and Vault becomes one *implementation* of this seam
+ * rather than the foundation — a choice a deployment makes, not a dependency it inherits.
+ *
+ * The honest trade-off, which belongs in the docs rather than in a footnote: app-side encryption means the
+ * application process holds the key in memory. Vault means the database performs the decryption and therefore
+ * sees plaintext. Neither is strictly better, and a deployment should pick knowing that.
+ *
+ * **The Vault implementation shipped in #268**, in `vault-cipher.ts`, and every clause of this file's test
+ * suite was run against a real Vault before it landed — which is why it was held back until one was available.
+ * Two properties differ from app-side sealing and are argued there rather than here: a Vault-sealed row holds
+ * a **pointer, not ciphertext**, which changes what a backup contains; and a pointer cannot be authenticated
+ * by what it points at, so integrity is provided by a binding token rather than by AEAD.
+ */
+/**
+ * A stored secret: ciphertext plus what is needed to read it back.
+ *
+ * `keyId` is the reason rotation is possible at all — see `createAesGcmCipher`. Everything here is safe to
+ * store beside the ciphertext; none of it is secret on its own.
+ */
+export type SealedSecret = {
+    /** Which key sealed this. A design with no key identity has a first key that is permanent. */
+    readonly keyId: string;
+    /** Algorithm, so a future one can be added without guessing what old rows used. */
+    readonly algorithm: string;
+    /** Base64. */
+    readonly nonce: string;
+    /** Base64, including the authentication tag. */
+    readonly ciphertext: string;
+};
+export interface SecretCipher {
+    seal(plaintext: string): Promise<SealedSecret>;
+    open(sealed: SealedSecret): Promise<string>;
+    /** The key new secrets are sealed with. Exposed so a rotation job can tell what still needs re-sealing. */
+    currentKeyId(): string;
+    /**
+     * Destroy whatever the sealed value refers to — **optional, and found by #268.**
+     *
+     * App-side sealing has nothing to implement: the ciphertext *is* the stored value, so deleting the row
+     * deletes the secret. A cipher that stores a **pointer** — Supabase Vault returns an id and keeps the
+     * ciphertext itself — does not, and dropping a connection row there leaves the credential behind, which is
+     * the opposite of what `docs/18` promises.
+     *
+     * Optional rather than required because most implementations genuinely have nothing to do, and a required
+     * no-op is a method every future cipher has to write in order to say "not applicable". A caller deleting a
+     * connection should call it when present.
+     */
+    forget?(sealed: SealedSecret): Promise<void>;
+}
+export declare const AES_GCM: "aes-256-gcm";
+export type AesKey = {
+    readonly id: string;
+    /** 32 bytes. A shorter key is a configuration error, not a weaker mode. */
+    readonly key: Buffer;
+};
+/**
+ * AES-256-GCM, with a key set rather than a key.
+ *
+ * **Rotation is why this takes a list.** A design with one key has a first key that is permanent: re-encrypting
+ * every stored secret requires reading them, which requires the old key, which the process no longer has. So
+ * every sealed secret records its `keyId`, `open` looks the key up, and rotation is: add a new key, make it
+ * current, re-seal in the background, retire the old one. A deployment that never rotates passes one key and
+ * notices nothing.
+ *
+ * **Authenticated encryption, and the authentication is the point.** GCM's tag means a tampered ciphertext
+ * *fails* rather than decrypting to something else. Without it, a byte flipped in a database row would produce
+ * garbage that gets sent to a vendor as a token — a failure that looks like an expired credential and is not.
+ */
+export declare const createAesGcmCipher: (input: {
+    readonly keys: readonly AesKey[];
+    readonly currentKeyId?: string;
+    readonly randomNonce?: () => Buffer;
+}) => SecretCipher;
+/** Constant-time comparison, for callers checking a sealed secret against another without leaking timing. */
+export declare const sealedEquals: (a: SealedSecret, b: SealedSecret) => boolean;
+//# sourceMappingURL=cipher.d.ts.map