@retinue/agentkit 0.1.0 → 0.3.0

package/dist/connections/pause.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A run that needs a connection pauses and asks — REQ-063 (#259), task #264.
+ *
+ * A tool call fails because the tenant has no connection, or the one they have expired or lacks a scope. Before
+ * this, that was `capability_unavailable`: the run died and a person read an error. Now it **pauses**, hands
+ * back a login URL, and resumes when consent completes.
+ *
+ * ## The third pause, not a new mechanism
+ *
+ * The runtime already does exactly this shape twice — `waiting-for-question` and `waiting-for-approval`, each
+ * with an event the engine emits, a status the worker parks in, and a resume to `queued`. Building a bespoke
+ * polling loop, or leaving a failed run for somebody to restart by hand, would be a second mechanism for the
+ * thing the durable runtime exists to do.
+ *
+ * ## Where it does **not** apply
+ *
+ * Only where a login URL exists. A token-based integration has nothing to redirect to, so a missing token must
+ * still fail with the message naming the ref. Getting this backwards produces the worst outcome available: a run
+ * that hangs for ever waiting for a consent screen nobody can reach.
+ *
+ * That decision comes from `ToolkitAuth.modes` (#260) — the reason `AuthMode` and `CredentialScheme` are
+ * separate axes. An OAuth access token is presented as a bearer, so a design that only knew the wire format
+ * could not answer this question at all.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import type { AuthMode } from "../tools/credentials.js";
+/**
+ * Why a connection is not usable. Three triggers, all of which should pause.
+ *
+ * Separate values because a UI says different things: "connect your GitHub" is not "your GitHub connection
+ * expired" is not "grant one more permission", and a person who is told the wrong one goes looking in the wrong
+ * place.
+ */
+export declare const CONNECTION_GAPS: readonly ["absent", "expired", "insufficient-scope"];
+export type ConnectionGap = (typeof CONNECTION_GAPS)[number];
+export type ConnectionNeed = {
+    readonly provider: string;
+    readonly gap: ConnectionGap;
+    /** Scopes the consent must ask for. For `insufficient-scope`, the missing ones plus what was already granted. */
+    readonly scopes: readonly string[];
+    readonly toolName?: string;
+};
+/**
+ * Recognises a failure as *a missing connection* rather than a broken tool.
+ *
+ * Structural rather than a string match on the message: a `details.connectionGap` set by the resolver, so
+ * rewording an error cannot silently turn a pausable failure into a fatal one. The marker is added by the
+ * connection resolver, which is the only code that knows the difference.
+ */
+export declare const connectionNeedOf: (thrown: unknown) => ConnectionNeed | null;
+/** Attaches the marker above to an error, so the engine can recognise it without parsing prose. */
+export declare const withConnectionGap: (error: AgentPlatformError, need: ConnectionNeed) => AgentPlatformError;
+/**
+ * Whether this provider can be connected by sending somebody somewhere — the branch that decides pause or fail.
+ *
+ * `undefined` modes means the host has not declared any, and the honest answer there is **no**: pausing a run
+ * for a provider that turns out to have no flow would hang it for ever, and failing is recoverable.
+ */
+export declare const canPauseForConsent: (modes: readonly AuthMode[] | undefined) => boolean;
+/**
+ * The message a person sees, per gap.
+ *
+ * Written here rather than in a UI so every client says the same thing, and so the distinction between the
+ * three gaps survives — a person told "connect your GitHub" when the real problem is a missing scope will
+ * disconnect and reconnect and land in exactly the same place.
+ */
+export declare const consentPrompt: (need: ConnectionNeed) => string;
+//# sourceMappingURL=pause.d.ts.map

package/dist/connections/pause.js

@@ -0,0 +1,97 @@
+/**
+ * A run that needs a connection pauses and asks — REQ-063 (#259), task #264.
+ *
+ * A tool call fails because the tenant has no connection, or the one they have expired or lacks a scope. Before
+ * this, that was `capability_unavailable`: the run died and a person read an error. Now it **pauses**, hands
+ * back a login URL, and resumes when consent completes.
+ *
+ * ## The third pause, not a new mechanism
+ *
+ * The runtime already does exactly this shape twice — `waiting-for-question` and `waiting-for-approval`, each
+ * with an event the engine emits, a status the worker parks in, and a resume to `queued`. Building a bespoke
+ * polling loop, or leaving a failed run for somebody to restart by hand, would be a second mechanism for the
+ * thing the durable runtime exists to do.
+ *
+ * ## Where it does **not** apply
+ *
+ * Only where a login URL exists. A token-based integration has nothing to redirect to, so a missing token must
+ * still fail with the message naming the ref. Getting this backwards produces the worst outcome available: a run
+ * that hangs for ever waiting for a consent screen nobody can reach.
+ *
+ * That decision comes from `ToolkitAuth.modes` (#260) — the reason `AuthMode` and `CredentialScheme` are
+ * separate axes. An OAuth access token is presented as a bearer, so a design that only knew the wire format
+ * could not answer this question at all.
+ */
+import { AgentPlatformError, isAgentPlatformError } from "../core/errors.js";
+/**
+ * Why a connection is not usable. Three triggers, all of which should pause.
+ *
+ * Separate values because a UI says different things: "connect your GitHub" is not "your GitHub connection
+ * expired" is not "grant one more permission", and a person who is told the wrong one goes looking in the wrong
+ * place.
+ */
+export const CONNECTION_GAPS = ["absent", "expired", "insufficient-scope"];
+/**
+ * Recognises a failure as *a missing connection* rather than a broken tool.
+ *
+ * Structural rather than a string match on the message: a `details.connectionGap` set by the resolver, so
+ * rewording an error cannot silently turn a pausable failure into a fatal one. The marker is added by the
+ * connection resolver, which is the only code that knows the difference.
+ */
+export const connectionNeedOf = (thrown) => {
+    if (!isAgentPlatformError(thrown))
+        return null;
+    const details = thrown.details;
+    const gap = details?.["connectionGap"];
+    const provider = details?.["connectionProvider"];
+    if (typeof gap !== "string" || !CONNECTION_GAPS.includes(gap))
+        return null;
+    if (typeof provider !== "string" || provider === "")
+        return null;
+    const scopes = details?.["connectionScopes"];
+    return {
+        provider,
+        gap: gap,
+        scopes: Array.isArray(scopes) ? scopes.filter((s) => typeof s === "string") : [],
+        ...(typeof details?.["toolName"] === "string" ? { toolName: details["toolName"] } : {}),
+    };
+};
+/** Attaches the marker above to an error, so the engine can recognise it without parsing prose. */
+export const withConnectionGap = (error, need) => new AgentPlatformError({
+    code: error.code,
+    message: error.message,
+    retryable: false,
+    details: {
+        ...(error.details ?? {}),
+        connectionGap: need.gap,
+        connectionProvider: need.provider,
+        connectionScopes: [...need.scopes],
+        ...(need.toolName === undefined ? {} : { toolName: need.toolName }),
+    },
+});
+/**
+ * Whether this provider can be connected by sending somebody somewhere — the branch that decides pause or fail.
+ *
+ * `undefined` modes means the host has not declared any, and the honest answer there is **no**: pausing a run
+ * for a provider that turns out to have no flow would hang it for ever, and failing is recoverable.
+ */
+export const canPauseForConsent = (modes) => modes !== undefined && modes.includes("oauth2");
+/**
+ * The message a person sees, per gap.
+ *
+ * Written here rather than in a UI so every client says the same thing, and so the distinction between the
+ * three gaps survives — a person told "connect your GitHub" when the real problem is a missing scope will
+ * disconnect and reconnect and land in exactly the same place.
+ */
+export const consentPrompt = (need) => {
+    switch (need.gap) {
+        case "absent":
+            return `Connect ${need.provider} to continue.`;
+        case "expired":
+            return `Your ${need.provider} connection expired. Reconnect to continue.`;
+        case "insufficient-scope":
+            return (`Your ${need.provider} connection needs ${need.scopes.join(", ") || "additional permissions"}. ` +
+                "Reconnect and grant them to continue.");
+    }
+};
+//# sourceMappingURL=pause.js.map

package/dist/connections/resolver.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A `CredentialResolver` over stored connections — the half that makes #260 useful, task #261.
+ *
+ * #260 made a credential a typed value and shipped one resolver: a static map, which serves exactly one tenant.
+ * This is the multi-tenant one, and it is the piece the whole integrations milestone was waiting for.
+ *
+ * ## Resolution is per call, and that is not an implementation detail
+ *
+ * `credentials.ts` explains why: a credential read once at startup survives its own rotation, and the failure
+ * looks like the vendor rejecting a token that "has not changed". This resolver therefore reads the store on
+ * every call and caches nothing. A deployment that wants caching adds it knowing its own rotation window —
+ * which is a decision only the deployment can make.
+ */
+import { type CredentialResolver, type CredentialScheme } from "../tools/credentials.js";
+import type { SecretCipher } from "./cipher.js";
+import { type Connection, type ConnectionStore } from "./index.js";
+export type ConnectionResolverDeps = {
+    readonly store: ConnectionStore;
+    readonly cipher: SecretCipher;
+    /**
+     * Which connection a bare `<provider>` ref means when a tenant has several.
+     *
+     * Defaults to the oldest, which is stable and explainable — "the first one you connected" — rather than
+     * newest, which would silently re-point every agent the moment somebody adds a second account.
+     */
+    readonly chooseDefault?: (candidates: readonly Connection[]) => Connection | undefined;
+};
+export declare const createConnectionCredentialResolver: (deps: ConnectionResolverDeps) => CredentialResolver;
+/** Which scheme a connection presents, for `assertToolkitAuth` at wiring time. */
+export declare const schemeOf: (connection: Connection) => CredentialScheme;
+/**
+ * Re-seals every connection that is not already under the current key — task #261 AC-7.
+ *
+ * Rotation without this is theory: `SecretCipher` can *open* an old key's secrets, but nothing moves them
+ * forward, so the old key can never be retired and the first key is permanent in practice.
+ *
+ * The order is what makes it safe to interrupt. Each connection is opened, re-sealed and written **one at a
+ * time**, and a failure leaves everything before it done and everything after it untouched — both readable,
+ * because the old key is still configured. Running it twice is a no-op: a connection already on the current key
+ * is skipped.
+ *
+ * Deliberately not a transaction over the whole tenant. A rotation across thousands of connections held in one
+ * transaction is a long-running write that blocks and, if it fails at the end, achieves nothing.
+ */
+export declare const resealConnections: (input: {
+    readonly store: ConnectionStore;
+    readonly cipher: SecretCipher;
+    readonly tenantId: string;
+    /** Reported per connection, so a long rotation is observable rather than silent. */
+    readonly onProgress?: (progress: {
+        readonly id: string;
+        readonly from: string;
+        readonly to: string;
+    }) => void;
+}) => Promise<{
+    readonly resealed: number;
+    readonly skipped: number;
+}>;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/connections/resolver.js

@@ -0,0 +1,138 @@
+/**
+ * A `CredentialResolver` over stored connections — the half that makes #260 useful, task #261.
+ *
+ * #260 made a credential a typed value and shipped one resolver: a static map, which serves exactly one tenant.
+ * This is the multi-tenant one, and it is the piece the whole integrations milestone was waiting for.
+ *
+ * ## Resolution is per call, and that is not an implementation detail
+ *
+ * `credentials.ts` explains why: a credential read once at startup survives its own rotation, and the failure
+ * looks like the vendor rejecting a token that "has not changed". This resolver therefore reads the store on
+ * every call and caches nothing. A deployment that wants caching adds it knowing its own rotation window —
+ * which is a decision only the deployment can make.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { createCredential, } from "../tools/credentials.js";
+import { parseCredentialRef } from "./index.js";
+import { withConnectionGap } from "./pause.js";
+/**
+ * How the plaintext behind a connection maps back to a `Credential`.
+ *
+ * The sealed blob holds **only** the secret parts — the token, or the password of a basic pair. Everything
+ * non-secret (the username, the header name, the metadata) is stored in readable columns, so listing
+ * connections needs no key and a person can see *which account* a connection is for without decrypting
+ * anything.
+ */
+const toCredential = (connection, plaintext) => {
+    const shared = {
+        mode: connection.mode,
+        ...(connection.metadata === undefined ? {} : { metadata: connection.metadata }),
+    };
+    switch (connection.scheme) {
+        case "bearer":
+            return createCredential({ scheme: "bearer", token: plaintext, ...shared });
+        case "basic": {
+            // The username lives in metadata because it is not a secret and a person needs to see it.
+            const username = connection.metadata?.username;
+            if (username === undefined)
+                throw new AgentPlatformError({
+                    code: "invalid_input",
+                    message: `connection "${connection.id}" is a basic credential with no \`metadata.username\`. The username is ` +
+                        "stored readable on purpose — a connection list should show which account it is for without a key.",
+                    retryable: false,
+                });
+            return createCredential({ scheme: "basic", username, password: plaintext, ...shared });
+        }
+        case "custom-header": {
+            const header = connection.metadata?.header;
+            if (header === undefined)
+                throw new AgentPlatformError({
+                    code: "invalid_input",
+                    message: `connection "${connection.id}" is a custom-header credential with no \`metadata.header\``,
+                    retryable: false,
+                });
+            return createCredential({ scheme: "custom-header", header, value: plaintext, ...shared });
+        }
+    }
+};
+export const createConnectionCredentialResolver = (deps) => {
+    const chooseDefault = deps.chooseDefault ?? ((candidates) => candidates[0]);
+    return {
+        async resolve({ ref, context }) {
+            const { provider, id } = parseCredentialRef(ref);
+            const connection = id === undefined
+                ? chooseDefault(await deps.store.list({ tenantId: context.tenantId, provider }))
+                : ((await deps.store.get({ tenantId: context.tenantId, id })) ?? undefined);
+            if (connection === undefined || connection === null)
+                // Marked, so the engine can recognise it as *a missing connection* rather than a broken tool and pause
+                // the run instead of failing it — #264. Structural, not a string match: rewording this message must not
+                // silently turn a pausable failure into a fatal one.
+                throw withConnectionGap(new AgentPlatformError({
+                    code: "capability_unavailable",
+                    message: `no ${provider} connection for this workspace` +
+                        (id === undefined ? "" : ` with id "${id}"`) +
+                        ". Connect one, or check the credential reference.",
+                    retryable: false,
+                }), { provider, gap: "absent", scopes: [] });
+            // A ref naming one provider must not resolve to another's credential, which is what a wrong id would do.
+            if (id !== undefined && connection.provider !== provider)
+                throw new AgentPlatformError({
+                    code: "invalid_input",
+                    message: `connection "${id}" is a ${connection.provider} connection, not ${provider}`,
+                    retryable: false,
+                });
+            /**
+             * Expiry is reported, not refreshed — refresh is #233's, deliberately.
+             *
+             * Saying "expired" rather than sending it is the difference between a message an operator can act on and
+             * a vendor 401 that says the token is invalid.
+             */
+            if (connection.expiresAt !== undefined && Date.parse(connection.expiresAt) <= Date.now())
+                throw withConnectionGap(new AgentPlatformError({
+                    code: "capability_unavailable",
+                    message: `the ${provider} connection expired at ${connection.expiresAt}. Reconnect, or wire a refresh.`,
+                    retryable: false,
+                }), { provider, gap: "expired", scopes: connection.grantedScopes ?? [] });
+            const plaintext = await deps.cipher.open(connection.sealed);
+            return toCredential(connection, plaintext);
+        },
+    };
+};
+/** Which scheme a connection presents, for `assertToolkitAuth` at wiring time. */
+export const schemeOf = (connection) => connection.scheme;
+/**
+ * Re-seals every connection that is not already under the current key — task #261 AC-7.
+ *
+ * Rotation without this is theory: `SecretCipher` can *open* an old key's secrets, but nothing moves them
+ * forward, so the old key can never be retired and the first key is permanent in practice.
+ *
+ * The order is what makes it safe to interrupt. Each connection is opened, re-sealed and written **one at a
+ * time**, and a failure leaves everything before it done and everything after it untouched — both readable,
+ * because the old key is still configured. Running it twice is a no-op: a connection already on the current key
+ * is skipped.
+ *
+ * Deliberately not a transaction over the whole tenant. A rotation across thousands of connections held in one
+ * transaction is a long-running write that blocks and, if it fails at the end, achieves nothing.
+ */
+export const resealConnections = async (input) => {
+    const current = input.cipher.currentKeyId();
+    const connections = await input.store.list({ tenantId: input.tenantId });
+    let resealed = 0;
+    let skipped = 0;
+    for (const connection of connections) {
+        if (connection.sealed.keyId === current) {
+            skipped += 1;
+            continue;
+        }
+        const plaintext = await input.cipher.open(connection.sealed);
+        await input.store.update({
+            tenantId: input.tenantId,
+            id: connection.id,
+            patch: { sealed: await input.cipher.seal(plaintext) },
+        });
+        input.onProgress?.({ id: connection.id, from: connection.sealed.keyId, to: current });
+        resealed += 1;
+    }
+    return { resealed, skipped };
+};
+//# sourceMappingURL=resolver.js.map

package/dist/connections/resume.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Resuming a run once consent completes — REQ-063 (#259), task #264, AC-3, AC-5, AC-6 and AC-7.
+ *
+ * The mirror of `hitl`'s `resumeRun`: transition back to `queued` and enqueue. The run picks up from its
+ * checkpoint and re-attempts the tool call that paused it, so nothing before the pause is repeated — the same
+ * idempotency the approval path already relies on.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { RunId } from "../core/ids.js";
+import type { RunEventLog } from "../core/events.js";
+import type { JobDispatcher } from "../runtime/index.js";
+import type { RunStore } from "../persistence/index.js";
+export type ConsentResumeDeps = {
+    readonly runs: RunStore;
+    readonly dispatcher: JobDispatcher;
+    readonly events?: RunEventLog;
+    readonly now?: () => string;
+};
+/**
+ * Resumes a run that was waiting for a connection.
+ *
+ * ## Only the right principal — AC-5
+ *
+ * This is the security property of the whole feature, and it is not about the run: it is about the **login
+ * URL**. That URL is rendered in a UI, appears in screenshots and may be pasted into a chat. If completing the
+ * flow it points at could resume *anyone's* run, a leaked URL would let a stranger attach their own account to
+ * somebody else's tenant — and every subsequent action the agent took against that provider would be theirs.
+ *
+ * So the run must belong to the caller's tenant. The OAuth flow has already bound its `state` to the tenant and
+ * the principal who began it (#262), which is the other half: the state cannot be redeemed by another person,
+ * and the resume cannot be driven from another tenant.
+ *
+ * ## Idempotent — AC-6
+ *
+ * A double-click, a retried redirect, a browser prefetch: the callback firing twice must queue the run **once**.
+ * `transition` is guarded by the current status, so a run already moved out of `waiting-for-connection` is
+ * reported as `resumed: false` rather than enqueued again — and a second job would mean the tool call that
+ * paused the run runs twice.
+ */
+export declare const resumeAfterConsent: (deps: ConsentResumeDeps, input: {
+    readonly context: ExecutionContext;
+    readonly runId: RunId;
+    readonly provider: string;
+    readonly connectionId: string;
+}) => Promise<{
+    readonly resumed: boolean;
+    readonly reason?: string;
+}>;
+/**
+ * Fails a run that has been waiting for a connection longer than the deployment allows — AC-7.
+ *
+ * A pause with no ceiling is a run that holds a row for ever, and the reaper does not sweep it: the reaper
+ * exists for *abandoned* runs, and this one is not abandoned — it is waiting for a person who is never coming
+ * back. So it needs its own ceiling, and failing with a reason beats a row nobody can explain.
+ */
+export declare const expireStaleConsents: (deps: ConsentResumeDeps & {
+    readonly listWaiting: (before: string) => Promise<readonly {
+        readonly tenantId: string;
+        readonly id: RunId;
+    }[]>;
+}, input: {
+    readonly olderThanMs: number;
+}) => Promise<number>;
+//# sourceMappingURL=resume.d.ts.map

package/dist/connections/resume.js

@@ -0,0 +1,99 @@
+/**
+ * Resuming a run once consent completes — REQ-063 (#259), task #264, AC-3, AC-5, AC-6 and AC-7.
+ *
+ * The mirror of `hitl`'s `resumeRun`: transition back to `queued` and enqueue. The run picks up from its
+ * checkpoint and re-attempts the tool call that paused it, so nothing before the pause is repeated — the same
+ * idempotency the approval path already relies on.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+/**
+ * Resumes a run that was waiting for a connection.
+ *
+ * ## Only the right principal — AC-5
+ *
+ * This is the security property of the whole feature, and it is not about the run: it is about the **login
+ * URL**. That URL is rendered in a UI, appears in screenshots and may be pasted into a chat. If completing the
+ * flow it points at could resume *anyone's* run, a leaked URL would let a stranger attach their own account to
+ * somebody else's tenant — and every subsequent action the agent took against that provider would be theirs.
+ *
+ * So the run must belong to the caller's tenant. The OAuth flow has already bound its `state` to the tenant and
+ * the principal who began it (#262), which is the other half: the state cannot be redeemed by another person,
+ * and the resume cannot be driven from another tenant.
+ *
+ * ## Idempotent — AC-6
+ *
+ * A double-click, a retried redirect, a browser prefetch: the callback firing twice must queue the run **once**.
+ * `transition` is guarded by the current status, so a run already moved out of `waiting-for-connection` is
+ * reported as `resumed: false` rather than enqueued again — and a second job would mean the tool call that
+ * paused the run runs twice.
+ */
+export const resumeAfterConsent = async (deps, input) => {
+    const now = deps.now ?? (() => new Date().toISOString());
+    const run = await deps.runs.findById({ tenantId: input.context.tenantId, id: input.runId });
+    if (run === null) {
+        /**
+         * Absent and not-yours are the same answer, deliberately.
+         *
+         * Distinguishing them tells a caller whether a run id exists in another tenant, which is exactly the probe
+         * a leaked login URL would be used for. `findById` is already tenant-scoped, so this branch covers both.
+         */
+        throw new AgentPlatformError({
+            code: "not_found",
+            message: `no run "${input.runId}" for this workspace`,
+            retryable: false,
+        });
+    }
+    if (run.status !== "waiting-for-connection") {
+        // Not an error: a retried callback on an already-resumed run is a normal thing a browser does.
+        return { resumed: false, reason: `the run is ${run.status}, not waiting for a connection` };
+    }
+    if (deps.events !== undefined) {
+        // Recorded before the transition, so a crash between the two leaves a log that says what happened rather
+        // than a run that moved for no visible reason.
+        await deps.events.append({
+            tenantId: input.context.tenantId,
+            event: {
+                type: "connection.completed",
+                runId: input.runId,
+                sequence: 0,
+                occurredAt: now(),
+                provider: input.provider,
+                connectionId: input.connectionId,
+            },
+        });
+    }
+    await deps.runs.transition({
+        tenantId: input.context.tenantId,
+        id: input.runId,
+        workerId: "connections",
+        to: "queued",
+        now: now(),
+    });
+    await deps.dispatcher.enqueueRun({ tenantId: input.context.tenantId, runId: input.runId });
+    return { resumed: true };
+};
+/**
+ * Fails a run that has been waiting for a connection longer than the deployment allows — AC-7.
+ *
+ * A pause with no ceiling is a run that holds a row for ever, and the reaper does not sweep it: the reaper
+ * exists for *abandoned* runs, and this one is not abandoned — it is waiting for a person who is never coming
+ * back. So it needs its own ceiling, and failing with a reason beats a row nobody can explain.
+ */
+export const expireStaleConsents = async (deps, input) => {
+    const now = deps.now ?? (() => new Date().toISOString());
+    const cutoff = new Date(Date.parse(now()) - input.olderThanMs).toISOString();
+    const stale = await deps.listWaiting(cutoff);
+    let failed = 0;
+    for (const run of stale) {
+        await deps.runs.transition({
+            tenantId: run.tenantId,
+            id: run.id,
+            workerId: "connections",
+            to: "failed",
+            now: now(),
+        });
+        failed += 1;
+    }
+    return failed;
+};
+//# sourceMappingURL=resume.js.map

package/dist/connections/vault-cipher.d.ts

@@ -0,0 +1,95 @@
+/**
+ * A `SecretCipher` over Supabase Vault — REQ-063 (#259), task #268.
+ *
+ * #261 shipped the seam with an app-side AES-256-GCM implementation and deliberately left this one out: there
+ * was no Vault to run it against, and an untested crypto implementation behind a seam that *looks* tested is
+ * worse than none. There is one now, and everything below has been run against it.
+ *
+ * ## The mapping, and the property it changes — AC-3
+ *
+ * Vault owns the ciphertext and hands back an **id**. The seam expects the caller to hold
+ * `{ keyId, algorithm, nonce, ciphertext }`. So:
+ *
+ * | Field | Holds |
+ * |---|---|
+ * | `algorithm` | `supabase-vault` — a sentinel, not a cipher name. The algorithm is Vault's business. |
+ * | `keyId` | `supabase-vault` — see the rotation note. Vault's own `key_id` column comes back **null**: the root key is held outside the database and Supabase does not expose an identity for it. |
+ * | `nonce` | A random **binding token**, not a nonce. See the tamper note. |
+ * | `ciphertext` | The Vault secret's **uuid**. Not ciphertext. |
+ *
+ * **A Vault-sealed row contains no secret material at all.** That is the property worth stating rather than
+ * discovering, and it cuts both ways:
+ *
+ * - A backup of the application's own tables carries no credentials — strictly better than app-side sealing,
+ *   where the backup carries ciphertext that a leaked key would open.
+ * - The secret lives in `vault.secrets`, so **restoring the application tables without the `vault` schema
+ *   leaves every connection pointing at nothing.** With app-side sealing the ciphertext travels with the row;
+ *   here it does not, and a backup strategy that covers `public` and not `vault` silently loses every
+ *   credential. That is a deployment fact, not a code one, and it belongs in a runbook.
+ *
+ * ## Deletion — AC-3, and a gap this found
+ *
+ * Deleting a connection row does **not** delete the Vault secret: the row held a pointer, and dropping a
+ * pointer leaves what it pointed at. `docs/18`'s deletion promises are therefore *not* satisfied by deleting
+ * the row alone, which is a difference from app-side sealing that nobody would notice until an audit.
+ *
+ * So `SecretCipher` gained an optional `forget`. App-side sealing has nothing to implement — the ciphertext
+ * dies with the row — and this implementation removes the Vault secret. A deployment on Vault that never calls
+ * it accumulates orphaned secrets that outlive the connections they belonged to.
+ *
+ * ## Tampering — AC-2, and where the guarantee genuinely differs
+ *
+ * AES-GCM authenticates: a flipped byte fails rather than decrypting to something else. A pointer cannot be
+ * authenticated by the thing it points at, so an attacker able to *write* the connections table could repoint
+ * one connection at another secret in the same Vault and read a credential they were not entitled to. That is
+ * a real weakening and it is not hypothetical — it is exactly the shape of a tenant-isolation bypass.
+ *
+ * Closed here with a **binding token**: `seal` stores a fresh 32-byte random value in the Vault secret's
+ * `description` and keeps it in the sealed value's `nonce` field; `open` compares them in constant time and
+ * refuses on mismatch. Repointing at another secret now fails, because that secret carries a different token.
+ * No application-side key is involved, so the "database cannot decrypt on its own" property is untouched.
+ *
+ * It is not equivalent to AEAD. An attacker who can write *both* the connections table and `vault.secrets`
+ * defeats it, where GCM would still fail. Stated rather than implied.
+ */
+import type { SecretCipher } from "./cipher.js";
+import type { SqlExecutor } from "../adapters/postgres/sql.js";
+/**
+ * The sentinel in `algorithm`, and the reason it is not a cipher name.
+ *
+ * A reader of a stored row needs to know *which implementation* sealed it, not which primitive. `aes-256-gcm`
+ * tells the app-side cipher how to open the value; `supabase-vault` tells this one that the value is a pointer.
+ * Putting libsodium's actual construction here would be a claim about Vault's internals that could stop being
+ * true without this package noticing.
+ */
+export declare const SUPABASE_VAULT: "supabase-vault";
+export type VaultCipherOptions = {
+    /**
+     * Runs the `vault.*` calls. A **service-role** executor: `vault.decrypted_secrets` is not readable by
+     * `anon` or `authenticated`, which is most of what makes Vault worth using.
+     */
+    readonly sql: SqlExecutor;
+    /**
+     * Prefix for the Vault secret's `name`.
+     *
+     * Named at all because `vault.secrets.name` is unique and a deployment sharing a database with anything else
+     * that writes to Vault would otherwise collide. The name carries no secret and is not used for integrity —
+     * that is the token's job.
+     */
+    readonly namePrefix?: string;
+    /** Injectable so a test can assert the token is fresh per seal rather than trusting that it is. */
+    readonly randomToken?: () => string;
+};
+export declare const createSupabaseVaultCipher: (options: VaultCipherOptions) => SecretCipher;
+/**
+ * Rotation is Vault's, not ours — AC-4, stated as a value so a test can assert it.
+ *
+ * `resealConnections` walks `sealed.keyId`; this cipher's is constant, so that walk finds nothing forever.
+ * Correct, and indistinguishable from a misconfigured rotation job unless somebody wrote it down.
+ */
+export declare const vaultRotationIsExternal: {
+    readonly cipher: "supabase-vault";
+    readonly resealFinds: "nothing, by design";
+    readonly why: string;
+};
+//# sourceMappingURL=vault-cipher.d.ts.map