@retinue/agentkit 0.2.0 → 0.3.0

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

package/dist/connections/cipher.js

@@ -0,0 +1,141 @@
+/**
+ * `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.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, timingSafeEqual } from "node:crypto";
+import { AgentPlatformError } from "../core/errors.js";
+export const AES_GCM = "aes-256-gcm";
+/** 96 bits, which is what GCM is specified for; a different length changes the security argument. */
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+/**
+ * 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 const createAesGcmCipher = (input) => {
+    if (input.keys.length === 0)
+        throw new Error("SecretCipher needs at least one key");
+    for (const { id, key } of input.keys) {
+        if (key.length !== 32)
+            throw new Error(`SecretCipher key "${id}" is ${key.length} bytes; AES-256 needs 32`);
+    }
+    const byId = new Map(input.keys.map((k) => [k.id, k.key]));
+    const currentId = input.currentKeyId ?? input.keys[0].id;
+    if (!byId.has(currentId))
+        throw new Error(`SecretCipher currentKeyId "${currentId}" is not among the keys`);
+    const nonceOf = input.randomNonce ?? (() => randomBytes(NONCE_BYTES));
+    return {
+        currentKeyId: () => currentId,
+        async seal(plaintext) {
+            const nonce = nonceOf();
+            if (nonce.length !== NONCE_BYTES)
+                throw new Error(`GCM nonce must be ${NONCE_BYTES} bytes`);
+            const cipher = createCipheriv(AES_GCM, byId.get(currentId), nonce);
+            const body = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+            // Tag appended rather than stored separately: one field cannot be reunited with the wrong other field.
+            return {
+                keyId: currentId,
+                algorithm: AES_GCM,
+                nonce: nonce.toString("base64"),
+                ciphertext: Buffer.concat([body, cipher.getAuthTag()]).toString("base64"),
+            };
+        },
+        async open(sealed) {
+            if (sealed.algorithm !== AES_GCM)
+                throw new AgentPlatformError({
+                    code: "capability_unavailable",
+                    message: `sealed with ${sealed.algorithm}, which this cipher cannot open`,
+                    retryable: false,
+                });
+            const key = byId.get(sealed.keyId);
+            if (key === undefined)
+                throw new AgentPlatformError({
+                    code: "capability_unavailable",
+                    // Named, because the remedy is specific: the key was retired before everything sealed with it was
+                    // re-sealed, and a rotation job needs to know which one to put back.
+                    message: `no key "${sealed.keyId}" is configured, so this secret cannot be opened. It was sealed with a key ` +
+                        "this process does not have — retire a key only after re-sealing everything that used it.",
+                    retryable: false,
+                });
+            const raw = Buffer.from(sealed.ciphertext, "base64");
+            if (raw.length < TAG_BYTES)
+                throw new AgentPlatformError({ code: "invalid_input", message: "ciphertext is too short to carry a tag", retryable: false });
+            const decipher = createDecipheriv(AES_GCM, key, Buffer.from(sealed.nonce, "base64"));
+            decipher.setAuthTag(raw.subarray(raw.length - TAG_BYTES));
+            try {
+                return Buffer.concat([decipher.update(raw.subarray(0, raw.length - TAG_BYTES)), decipher.final()]).toString("utf8");
+            }
+            catch {
+                /**
+                 * A tampered or corrupt secret **fails**, and this is the branch that matters.
+                 *
+                 * Without authentication a flipped byte decrypts to garbage, and garbage gets sent to a vendor as a
+                 * token — which looks like an expired credential and sends an operator to rotate something that was
+                 * never wrong. The message says what happened rather than what it looks like.
+                 */
+                throw new AgentPlatformError({
+                    code: "invalid_input",
+                    message: "this secret failed authentication: it was modified after being sealed, or was sealed with a " +
+                        "different key. It is deliberately not returned — an unauthenticated decryption yields bytes that " +
+                        "would be sent to a vendor as a credential.",
+                    retryable: false,
+                });
+            }
+        },
+    };
+};
+/** Constant-time comparison, for callers checking a sealed secret against another without leaking timing. */
+export const sealedEquals = (a, b) => {
+    if (a.keyId !== b.keyId || a.algorithm !== b.algorithm || a.nonce !== b.nonce)
+        return false;
+    const left = Buffer.from(a.ciphertext, "base64");
+    const right = Buffer.from(b.ciphertext, "base64");
+    return left.length === right.length && timingSafeEqual(left, right);
+};
+//# sourceMappingURL=cipher.js.map

package/dist/connections/index.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Connections — a tenant's link to a third-party provider. REQ-063 (#259), task #261.
+ *
+ * `docs/21` assigned this to the platform repository and `docs/21`'s amendment moved the runtime half here,
+ * because eight toolkits ship in this package and none of them was usable by a second tenant: every one takes a
+ * `credentialRef` and the only resolver that shipped was a static map.
+ *
+ * ## What a connection is, and is not
+ *
+ * It is **one tenant's authorisation to reach one provider**. It is not a toolkit's configuration: a base URL
+ * or a page size is the same for every tenant and belongs where the toolkit is wired. The dividing line is
+ * whether two tenants using the same toolkit would differ, and for a credential they always do.
+ *
+ * ## Several per tenant, per provider
+ *
+ * A customer with three GitHub organisations or two Slack workspaces is the normal case, not an edge one. So a
+ * connection has its own id, a provider, and an optional label a person chose — and `credentialRef` addresses a
+ * **connection**, with a per-tenant default per provider so the common single-connection case stays a one-word
+ * ref.
+ *
+ * ## The secret is opaque here
+ *
+ * The store holds a `SealedSecret` and cannot read it. That is what lets the same port sit over Postgres,
+ * Supabase and memory with the identical guarantee, and it is why `SecretCipher` is a separate seam rather than
+ * a detail of one adapter — see `cipher.ts` for why `pgcrypto` and Vault-only were both rejected.
+ */
+import type { TenantScope } from "../core/context.js";
+import type { AuthMode, CredentialScheme } from "../tools/credentials.js";
+import type { SealedSecret } from "./cipher.js";
+export type ConnectionId = string;
+/**
+ * A tenant's connection to a provider.
+ *
+ * Everything here is safe to read and to log, including `sealed` — which is ciphertext, not a secret. The name
+ * is the point: a connection list is a screen a person looks at, and rendering it must not need a key.
+ */
+/**
+ * What a stored row *is* — REQ-063 (#259), task #263.
+ *
+ * A tenant's own OAuth **app registration** is the same kind of record as a connection: tenant-scoped,
+ * provider-keyed, holding exactly one sealed secret, with metadata beside it, revocable, and covered by the same
+ * retention promise. So it is the same table with a discriminator rather than a second port, a second adapter
+ * family, a second migration, a second RLS policy and a second conformance suite for a record of identical
+ * shape.
+ *
+ * The discriminator is load-bearing, not cosmetic: `list` and `get` return **connections only** unless asked
+ * otherwise, so a credential resolver can never hand a toolkit a client secret by accident.
+ */
+export declare const CONNECTION_KINDS: readonly ["connection", "oauth-app"];
+export type ConnectionKind = (typeof CONNECTION_KINDS)[number];
+export type Connection = {
+    readonly id: ConnectionId;
+    /** Defaults to `"connection"`, so every existing row and caller means what it always did. */
+    readonly kind?: ConnectionKind;
+    /** `github`, `slack`, `google` — the toolkit's own name, so a ref can be resolved without a second lookup. */
+    readonly provider: string;
+    /** What a person called it: "Acme org", "#support workspace". Absent for a connection nobody named. */
+    readonly label?: string;
+    readonly mode: AuthMode;
+    readonly scheme: CredentialScheme;
+    /**
+     * Non-secret vendor identifiers discovered at connection time — Atlassian's cloud id, WhatsApp's phone
+     * number id. Stored beside the secret rather than inside it, so listing connections needs no key.
+     */
+    readonly metadata?: Readonly<Record<string, string>>;
+    /**
+     * Scopes the tenant actually granted.
+     *
+     * Recorded because a scope check must read what was *granted*, not what the deployment's app requests: a
+     * tenant using their own OAuth app (#263) may have granted a different set, and #259's AC-7 — telling someone
+     * to *reconnect and grant X* rather than surfacing a 403 — is answerable only from this.
+     */
+    readonly grantedScopes?: readonly string[];
+    readonly sealed: SealedSecret;
+    /** Present for a credential that expires; `undefined` for a long-lived token. Refresh is #233's. */
+    readonly expiresAt?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /**
+     * Set when a connection is revoked but kept for the audit trail.
+     *
+     * Soft, because "who connected this and when was it removed" is a question a security review asks, and a
+     * hard delete makes it unanswerable. A revoked connection never resolves.
+     */
+    readonly revokedAt?: string;
+};
+export type ConnectionInput = Omit<Connection, "createdAt" | "updatedAt" | "revokedAt">;
+export type ConnectionPatch = {
+    readonly label?: string;
+    readonly sealed?: SealedSecret;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly grantedScopes?: readonly string[];
+    readonly expiresAt?: string;
+};
+/**
+ * Where a tenant's connections live.
+ *
+ * Tenant-scoped on every method, with no `findById(id)` — governing principle 1. The store never sees a
+ * plaintext secret, so an adapter cannot leak one it does not have.
+ */
+export interface ConnectionStore {
+    create(input: TenantScope & {
+        readonly connection: ConnectionInput;
+    }): Promise<Connection>;
+    get(input: TenantScope & {
+        readonly id: ConnectionId;
+        readonly kind?: ConnectionKind;
+    }): Promise<Connection | null>;
+    /**
+     * Every live connection, optionally narrowed to one provider. Revoked ones are excluded.
+     *
+     * `kind` defaults to `"connection"`, so a caller that does not ask cannot receive an OAuth app registration —
+     * which is what stops a credential resolver handing a toolkit a client secret.
+     */
+    list(input: TenantScope & {
+        readonly provider?: string;
+        readonly kind?: ConnectionKind;
+    }): Promise<readonly Connection[]>;
+    update(input: TenantScope & {
+        readonly id: ConnectionId;
+        readonly patch: ConnectionPatch;
+    }): Promise<Connection>;
+    /** Marks it revoked. The row stays, so the audit trail survives. */
+    revoke(input: TenantScope & {
+        readonly id: ConnectionId;
+    }): Promise<void>;
+    /**
+     * Removes a tenant's connections entirely — `docs/18`'s retention, and the one hard delete.
+     *
+     * Deleting a tenant must remove their secrets: a soft-deleted credential is still a credential, and "we kept
+     * it for the audit trail" is not an answer to "delete my data".
+     */
+    purge(input: TenantScope): Promise<number>;
+}
+/**
+ * Which connection a `credentialRef` names.
+ *
+ * Two shapes, and both are needed. `provider` alone means "this tenant's default connection for GitHub", which
+ * keeps the single-connection case a one-word ref and is what almost every deployment writes. `provider:id`
+ * addresses one of several, which is what a customer with three organisations needs.
+ *
+ * Parsed rather than guessed, so a provider name containing a colon fails loudly instead of resolving to
+ * something surprising.
+ */
+export declare const parseCredentialRef: (ref: string) => {
+    readonly provider: string;
+    readonly id?: ConnectionId;
+};
+export * from "./cipher.js";
+export * from "./resolver.js";
+export * from "./oauth/index.js";
+export * from "./oauth/service.js";
+export * from "./oauth/client.js";
+export * from "./pause.js";
+export * from "./resume.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/connections/index.js

@@ -0,0 +1,72 @@
+/**
+ * Connections — a tenant's link to a third-party provider. REQ-063 (#259), task #261.
+ *
+ * `docs/21` assigned this to the platform repository and `docs/21`'s amendment moved the runtime half here,
+ * because eight toolkits ship in this package and none of them was usable by a second tenant: every one takes a
+ * `credentialRef` and the only resolver that shipped was a static map.
+ *
+ * ## What a connection is, and is not
+ *
+ * It is **one tenant's authorisation to reach one provider**. It is not a toolkit's configuration: a base URL
+ * or a page size is the same for every tenant and belongs where the toolkit is wired. The dividing line is
+ * whether two tenants using the same toolkit would differ, and for a credential they always do.
+ *
+ * ## Several per tenant, per provider
+ *
+ * A customer with three GitHub organisations or two Slack workspaces is the normal case, not an edge one. So a
+ * connection has its own id, a provider, and an optional label a person chose — and `credentialRef` addresses a
+ * **connection**, with a per-tenant default per provider so the common single-connection case stays a one-word
+ * ref.
+ *
+ * ## The secret is opaque here
+ *
+ * The store holds a `SealedSecret` and cannot read it. That is what lets the same port sit over Postgres,
+ * Supabase and memory with the identical guarantee, and it is why `SecretCipher` is a separate seam rather than
+ * a detail of one adapter — see `cipher.ts` for why `pgcrypto` and Vault-only were both rejected.
+ */
+/**
+ * A tenant's connection to a provider.
+ *
+ * Everything here is safe to read and to log, including `sealed` — which is ciphertext, not a secret. The name
+ * is the point: a connection list is a screen a person looks at, and rendering it must not need a key.
+ */
+/**
+ * What a stored row *is* — REQ-063 (#259), task #263.
+ *
+ * A tenant's own OAuth **app registration** is the same kind of record as a connection: tenant-scoped,
+ * provider-keyed, holding exactly one sealed secret, with metadata beside it, revocable, and covered by the same
+ * retention promise. So it is the same table with a discriminator rather than a second port, a second adapter
+ * family, a second migration, a second RLS policy and a second conformance suite for a record of identical
+ * shape.
+ *
+ * The discriminator is load-bearing, not cosmetic: `list` and `get` return **connections only** unless asked
+ * otherwise, so a credential resolver can never hand a toolkit a client secret by accident.
+ */
+export const CONNECTION_KINDS = ["connection", "oauth-app"];
+/**
+ * Which connection a `credentialRef` names.
+ *
+ * Two shapes, and both are needed. `provider` alone means "this tenant's default connection for GitHub", which
+ * keeps the single-connection case a one-word ref and is what almost every deployment writes. `provider:id`
+ * addresses one of several, which is what a customer with three organisations needs.
+ *
+ * Parsed rather than guessed, so a provider name containing a colon fails loudly instead of resolving to
+ * something surprising.
+ */
+export const parseCredentialRef = (ref) => {
+    const parts = ref.split(":");
+    if (parts.length === 1)
+        return { provider: parts[0] };
+    if (parts.length === 2 && parts[0] !== "" && parts[1] !== "")
+        return { provider: parts[0], id: parts[1] };
+    throw new Error(`credential reference "${ref}" is not "<provider>" or "<provider>:<connectionId>". A provider name ` +
+        "containing a colon would otherwise resolve to a connection nobody meant.");
+};
+export * from "./cipher.js";
+export * from "./resolver.js";
+export * from "./oauth/index.js";
+export * from "./oauth/service.js";
+export * from "./oauth/client.js";
+export * from "./pause.js";
+export * from "./resume.js";
+//# sourceMappingURL=index.js.map

package/dist/connections/oauth/client.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Which OAuth app a tenant connects through — REQ-063 (#259), task #263.
+ *
+ * Two ways to reach a provider, and both must work.
+ *
+ * **The deployment's shared app.** One registration per provider; every tenant consents to it. Simplest for the
+ * customer — nothing to register — and the path most will take.
+ *
+ * **The tenant's own app.** A customer who already has a registered Slack app, GitHub App or Google Cloud
+ * project uses their own client id and secret. This is not a nicety. Meta's app review is per app, so a shared
+ * app's approved use case may not cover a customer's; X's access tier is per app, so a customer paying for a
+ * higher tier gains nothing from a shared one on a lower; and an enterprise whose security team will not
+ * approve a third-party app in their Google tenant has no other route.
+ *
+ * ## The fallback is explicit, never silent
+ *
+ * `resolveOAuthClient` reports **which** app it chose. A caller that logs or displays it can see the difference;
+ * one that ignores it behaves as before. The reason is AC-7: removing a tenant's app configuration must not
+ * quietly migrate their live connections to the shared app, because that is a credential swap nobody
+ * authorised — the tokens were issued by a client that no longer participates, and the shared app cannot
+ * refresh or revoke them.
+ */
+import type { ExecutionContext } from "../../core/context.js";
+import type { SecretCipher } from "../cipher.js";
+import type { Connection, ConnectionStore } from "../index.js";
+import { type OAuthProviderConfig } from "./index.js";
+/** Which registration a flow is running under, and where it came from. */
+export type ResolvedOAuthClient = {
+    readonly clientId: string;
+    readonly clientSecret?: string;
+    readonly redirectUris: readonly string[];
+    readonly scopes: readonly string[];
+    readonly source: "tenant" | "deployment";
+    /** The connection id of the tenant's registration, when `source` is `"tenant"`. */
+    readonly registrationId?: string;
+};
+/**
+ * A tenant's registration, stored as an `oauth-app` row.
+ *
+ * The client secret is sealed by the same `SecretCipher` as every token — AC-2 — because it is exactly as much
+ * a secret and exactly as much the tenant's. The client id, redirect URI and scopes are metadata, readable,
+ * because a settings screen should render without a key.
+ */
+export declare const registerTenantOAuthApp: (input: {
+    readonly store: ConnectionStore;
+    readonly cipher: SecretCipher;
+    readonly context: ExecutionContext;
+    readonly provider: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly redirectUris: readonly string[];
+    readonly scopes?: readonly string[];
+    readonly id?: string;
+    readonly label?: string;
+}) => Promise<Connection>;
+/**
+ * The client this tenant connects through — theirs if registered, otherwise the deployment's.
+ *
+ * A tenant's own app brings its **own** redirect URIs, and they are still allowlisted: this is the obvious place
+ * that check gets loosened into a wildcard to make BYO work, and the whole of #262's second defence would go
+ * with it. The registration's URIs simply *become* the allowlist for that tenant's flow — an allowlist chosen by
+ * the customer, not a pattern.
+ */
+export declare const resolveOAuthClient: (input: {
+    readonly store: ConnectionStore;
+    readonly cipher: SecretCipher;
+    readonly context: ExecutionContext;
+    readonly config: OAuthProviderConfig;
+}) => Promise<ResolvedOAuthClient>;
+/** The provider config a flow should run with, for this tenant. */
+export declare const configForTenant: (base: OAuthProviderConfig, client: ResolvedOAuthClient) => OAuthProviderConfig;
+/**
+ * Refuses to use a connection with a client that did not issue it — AC-4.
+ *
+ * A token obtained through one app is not usable through another: refresh and revocation both authenticate as
+ * the client, so a connection whose client changed underneath it fails at the provider with a message about an
+ * invalid client — which reads as "your integration is broken" and sends nobody to the actual cause.
+ *
+ * Failing loudly here, naming both clients, is the difference between a five-minute fix and an afternoon.
+ */
+export declare const assertClientMatches: (connection: Connection, client: ResolvedOAuthClient) => void;
+/** Whether a redirect is allowed for this tenant's resolved client. Exactly matched, as always. */
+export declare const isAllowedRedirectForClient: (client: ResolvedOAuthClient, candidate: string) => boolean;
+//# sourceMappingURL=client.d.ts.map