@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/routes/webhooks.ts

@@ -0,0 +1,296 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { randomUUID } from 'node:crypto';
+
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+
+import type { Cursor, TenantId, TriggerId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type {
+  RegisterWebhookTriggerInput,
+  TriggerRegistryBinding,
+  UpdateWebhookTriggerInput,
+  WebhookTriggerRecord,
+} from '../trigger-binding.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit } from './pagination.js';
+
+/**
+ * Webhook triggers — fire a flow run when an HMAC-signed request
+ * arrives at the receiver URL.
+ *
+ * Seven admin routes on this file. The unauthenticated external
+ * receiver is not part of this router.
+ *
+ * Admin URLs use `:triggerId` (the row id) for consistency with
+ * schedules and event-triggers. Response bodies include `webhookId`
+ * (the routable identifier) so clients can compose the receiver URL.
+ *
+ * HMAC secrets — never plaintext on this row. The register body
+ * carries `hmacSecretName`, a handle into the tenant secrets store the
+ * caller wrote to first via `POST /v1/secrets`. Rotation flows through
+ * `POST /v1/secrets/:name/rotate` — trigger row untouched.
+ */
+export function webhooksRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  // ---------- POST / (register) ----------
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+
+    const parsed = await parseJsonObject(c, requestId);
+    if (parsed.kind === 'err') return parsed.response;
+    const body = parsed.value;
+
+    const flowId = requireString(body, 'flowId');
+    const flowVersion = requireString(body, 'flowVersion');
+    const hmacSecretName = requireString(body, 'hmacSecretName');
+    if (flowId.kind === 'err') return bad(c, requestId, flowId.message);
+    if (flowVersion.kind === 'err') return bad(c, requestId, flowVersion.message);
+    if (hmacSecretName.kind === 'err') return bad(c, requestId, hmacSecretName.message);
+
+    const rawConfig = (body.config ?? {}) as Record<string, unknown>;
+    // Route mints the webhookId — a random UUID, returned so the caller
+    // learns the receiver URL from the response.
+    const webhookId = randomUUID();
+
+    const registerInput: RegisterWebhookTriggerInput = {
+      kind: 'webhook',
+      tenantId,
+      flowId: flowId.value,
+      flowVersion: flowVersion.value,
+      config: {
+        ...('input' in rawConfig && { input: rawConfig.input }),
+      },
+      webhookId,
+      hmacSecretName: hmacSecretName.value,
+      ...(typeof body.label === 'string' && body.label.length > 0 && { label: body.label }),
+    };
+
+    const result = await binding.register(registerInput);
+    if (result.kind === 'err') {
+      c.status(statusFor(result.error.code) as never);
+      return c.json(
+        toWireError({ code: result.error.code, message: result.error.message }, requestId),
+      );
+    }
+    c.status(201);
+    return c.json(serializeWebhook(result.value as WebhookTriggerRecord));
+  });
+
+  // ---------- GET / (list) ----------
+  r.get('/', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const limit = clampLimit(c.req.query('limit'));
+    const cursorRaw = c.req.query('cursor');
+    const statusRaw = c.req.query('status');
+
+    let statusFilter: 'active' | 'paused' | undefined;
+    if (statusRaw === 'active' || statusRaw === 'paused') statusFilter = statusRaw;
+
+    const page = await binding.list({
+      tenantId,
+      kind: 'webhook',
+      limit,
+      ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw as Cursor }),
+      ...(statusFilter !== undefined && { status: statusFilter }),
+    });
+    return c.json({
+      data: page.data.map((row) => serializeWebhook(row as WebhookTriggerRecord)),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /:triggerId (get) ----------
+  r.get('/:triggerId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+
+    const rec = await binding.get({ tenantId, triggerId });
+    if (rec === null || rec.kind !== 'webhook') return notFound(c, requestId, triggerId);
+    return c.json(serializeWebhook(rec));
+  });
+
+  // ---------- PATCH /:triggerId (update) ----------
+  r.patch('/:triggerId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+
+    const parsed = await parseJsonObject(c, requestId);
+    if (parsed.kind === 'err') return parsed.response;
+    const body = parsed.value;
+
+    const patchConfig = body.config as Record<string, unknown> | undefined;
+    const cfg: Partial<{ input: unknown }> = {};
+    if (patchConfig !== undefined && 'input' in patchConfig) cfg.input = patchConfig.input;
+
+    const updateInput: UpdateWebhookTriggerInput = {
+      kind: 'webhook',
+      tenantId,
+      triggerId,
+      ...(Object.keys(cfg).length > 0 && { config: cfg }),
+      ...('label' in body && { label: body.label === null ? null : (body.label as string) }),
+      ...(typeof body.flowVersion === 'string' && { flowVersion: body.flowVersion }),
+    };
+
+    const result = await binding.update(updateInput);
+    if (result.kind === 'err') {
+      c.status(statusFor(result.error.code) as never);
+      return c.json(
+        toWireError(
+          {
+            code: result.error.code,
+            message: result.error.message,
+            triggerId: triggerId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json(serializeWebhook(result.value as WebhookTriggerRecord));
+  });
+
+  // ---------- POST /:triggerId/pause ----------
+  r.post('/:triggerId/pause', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+    const result = await binding.pause({ tenantId, triggerId });
+    if (result.kind === 'err') return lifecycleError(c, requestId, result.error, triggerId);
+    return c.json(serializeWebhook(result.value as WebhookTriggerRecord));
+  });
+
+  // ---------- POST /:triggerId/resume ----------
+  r.post('/:triggerId/resume', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+    const result = await binding.resume({ tenantId, triggerId });
+    if (result.kind === 'err') return lifecycleError(c, requestId, result.error, triggerId);
+    return c.json(serializeWebhook(result.value as WebhookTriggerRecord));
+  });
+
+  // ---------- POST /:triggerId/unregister (soft delete) ----------
+  r.post('/:triggerId/unregister', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+    const outcome = await binding.unregister({ tenantId, triggerId });
+    return c.json({
+      triggerId: triggerId as unknown as string,
+      unregistered: outcome.unregistered,
+    });
+  });
+
+  return r;
+}
+
+function serializeWebhook(r: WebhookTriggerRecord): Record<string, unknown> {
+  return {
+    triggerId: r.triggerId as unknown as string,
+    webhookId: r.webhookId,
+    flowId: r.flowId,
+    flowVersion: r.flowVersion,
+    ...(r.config.input !== undefined && { input: r.config.input }),
+    hmacSecretName: r.hmacSecretName,
+    label: r.label,
+    status: r.status,
+    lastFiredAt: r.lastFiredAt,
+    createdAt: r.createdAt,
+    updatedAt: r.updatedAt,
+  };
+}
+
+type ParseOk<T> = { readonly kind: 'ok'; readonly value: T };
+type ParseErr = { readonly kind: 'err'; readonly response: Response };
+
+async function parseJsonObject(
+  c: Context<AppEnv>,
+  requestId: string,
+): Promise<ParseOk<Record<string, unknown>> | ParseErr> {
+  let body: unknown;
+  try {
+    body = await c.req.json();
+  } catch {
+    c.status(statusFor('bad-input') as never);
+    return {
+      kind: 'err',
+      response: c.json(
+        toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId),
+      ),
+    };
+  }
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    c.status(statusFor('bad-input') as never);
+    return {
+      kind: 'err',
+      response: c.json(
+        toWireError(
+          { code: 'bad-input', message: 'Request body must be a JSON object' },
+          requestId,
+        ),
+      ),
+    };
+  }
+  return { kind: 'ok', value: body as Record<string, unknown> };
+}
+
+function requireString(
+  obj: unknown,
+  path: string,
+):
+  | { readonly kind: 'ok'; readonly value: string }
+  | { readonly kind: 'err'; readonly message: string } {
+  const parts = path.split('.');
+  let cur: unknown = obj;
+  for (const part of parts) {
+    if (cur === null || typeof cur !== 'object') {
+      return { kind: 'err', message: `\`${path}\` is required` };
+    }
+    cur = (cur as Record<string, unknown>)[part];
+  }
+  if (typeof cur !== 'string' || cur.length === 0) {
+    return { kind: 'err', message: `\`${path}\` is required` };
+  }
+  return { kind: 'ok', value: cur };
+}
+
+function bad(c: Context<AppEnv>, requestId: string, message: string): Response {
+  c.status(statusFor('bad-input') as never);
+  return c.json(toWireError({ code: 'bad-input', message }, requestId));
+}
+
+function notFound(c: Context<AppEnv>, requestId: string, triggerId: TriggerId): Response {
+  c.status(statusFor('trigger-not-found') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'trigger-not-found',
+        message: `No trigger with id "${triggerId as unknown as string}"`,
+        triggerId: triggerId as unknown as string,
+      },
+      requestId,
+    ),
+  );
+}
+
+function lifecycleError(
+  c: Context<AppEnv>,
+  requestId: string,
+  error: { readonly code: string; readonly message: string },
+  triggerId: TriggerId,
+): Response {
+  c.status(statusFor(error.code) as never);
+  return c.json(
+    toWireError(
+      { code: error.code, message: error.message, triggerId: triggerId as unknown as string },
+      requestId,
+    ),
+  );
+}

package/src/s3-credential-binding.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for AWS-style credentials that authenticate
+ * against the S3-compat `/s3/*` wire surface. Mirrors the
+ * `TokenResolver` shape (auth.ts): resolve an `accessKeyId` to a
+ * `S3Credential`, or `null` for missing / expired / revoked.
+ *
+ * Every deployment owns credential issuance out-of-band (an admin
+ * route or an operator console). This binding only resolves; it
+ * does not mint. Deployments typically issue credentials paired 1-to-1
+ * with a bucket + tenant.
+ *
+ * The SigV4 middleware calls `resolve(accessKeyId)` on every request,
+ * uses `secretKey` to recompute the expected signature, and if the
+ * comparison passes, sets `c.set('tenantId', credential.tenantId)` +
+ * `c.set('bucket', credential.bucket)` for downstream routes. The
+ * caller-supplied bucket in the URL is compared to `credential.bucket`
+ * — mismatch → `403 AccessDenied` (bucket-scoped credentials).
+ *
+ * ## Scope classification
+ *
+ * S3 credentials are a policy/config-scoped resource. This binding
+ * does not carry the uniform `{ scope?: Scope, inherit?: boolean }`
+ * filter fields because it exposes only a runtime-bound
+ * `resolve(accessKeyId)` entry-point — no `list()` / `*ListInput` /
+ * filter surface. The Scope discipline still applies to stored
+ * credentials (each carries a tenant / org / project scope, like MCP
+ * endpoints), and a `list()` method — if added for an admin plane —
+ * must gain the same `{ scope?: Scope, inherit?: boolean }` shape
+ * (policy/config semantics: `inherit` load-bearing). There is no admin
+ * list surface.
+ */
+export type S3CredentialBinding = {
+  resolve(accessKeyId: string): Promise<S3Credential | null>;
+};
+
+export interface S3Credential {
+  /** Long-form secret paired with `accessKeyId`; used to recompute SigV4. */
+  readonly secretKey: string;
+  /** Which tenant this credential belongs to. */
+  readonly tenantId: TenantId;
+  /**
+   * Which bucket this credential is authorized for. One bucket per
+   * credential. Requests for other buckets return `403 AccessDenied`.
+   * The `artifacts` bucket is where bespoke uploads conventionally land
+   * — credentials granted this bucket see bespoke uploads too.
+   */
+  readonly bucket: string;
+  /**
+   * Optional expiration. If set and past, the middleware treats the
+   * credential as expired even if this resolver returned it.
+   */
+  readonly expiresAt?: Date;
+}

package/src/secrets-binding.ts

@@ -0,0 +1,308 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import type { Scope } from '@kindgi/platform';
+import type { Cursor, EnvName, Result } from '@kindgi/types';
+
+/**
+ * Secret names starting with this prefix are reserved for framework-internal
+ * material (e.g. webhook HMAC keys the runtime manages). `SecretBinding.set` rejects them
+ * from callers unless the adapter was constructed to allow reserved names.
+ * Every adapter enforces the same prefix — import it, don't redefine it.
+ */
+export const RESERVED_SECRET_NAME_PREFIX = 'kindgi.';
+
+/**
+ * Caller-plugged secret store — the framework consumer's surface for
+ * every secret-lifecycle op. Every method is scope + env-scoped, where
+ * `scope` is the discriminated primitive from `@kindgi/platform`
+ * (Tenant / Org / Project). Writes declare the scope explicitly; reads
+ * resolve via most-specific-wins walk across the scope hierarchy.
+ *
+ * Callers (routes, runtime dispatch, SDK clients) speak this interface
+ * ONLY. Concrete storage — envelope-encrypted bytes in a database,
+ * delegation to an external secret manager, etc. — is a `SecretBinding`
+ * implementation choice.
+ *
+ * Wire-safety: plaintext is returned only by `resolve`. `SecretRecord`
+ * carries no value, and `SecretVersionRecord.value` is always `null`
+ * from `getVersion` / `listVersions`. All list / get paths return
+ * metadata only. This is a STRUCTURAL guardrail of the interface, not
+ * a caller convention.
+ *
+ * Env-safety: cross-env reads are refused. A caller in `envName:
+ * staging` cannot resolve a secret written under `envName: production`
+ * — adapter returns `secret-not-found` (indistinguishable from
+ * "doesn't exist" by design; refuses to leak the existence of a
+ * cross-env sibling).
+ */
+export interface SecretBinding {
+  // -------------------- read --------------------
+
+  /** Cursor-paginated list of secret metadata. Never returns `value`. */
+  list(input: SecretListInput): Promise<SecretListPage>;
+
+  /** Fetch metadata for a single secret. `null` when unknown. */
+  get(input: SecretGetInput): Promise<SecretRecord | null>;
+
+  /**
+   * Resolve a secret's plaintext value at dispatch time. Distinct
+   * method from `get` — different capability gate, different audit
+   * event, different rate profile. Called by the runtime (handler
+   * dispatch, deploy-time sync, boot — see `ResolveContext.caller`),
+   * not by the HTTP routes. Emits a `secret-resolved` compliance-evidence
+   * event on every call.
+   */
+  resolve(input: SecretResolveInput): Promise<Result<SecretResolveOutcome, SecretError>>;
+
+  /** Metadata for a specific version. */
+  getVersion(input: SecretGetVersionInput): Promise<SecretVersionRecord | null>;
+
+  /** List all versions for a secret. Metadata only. */
+  listVersions(input: SecretListVersionsInput): Promise<SecretVersionPage>;
+
+  // -------------------- write --------------------
+
+  /**
+   * Create a secret OR write a new version. `writeMode` discriminates:
+   *   - `'create-new'` fails with `already-exists` if the secret exists
+   *   - `'add-version'` writes a new version, bumps counter atomically
+   */
+  set(input: SecretSetInput): Promise<SecretSetOutcome>;
+
+  /**
+   * Explicit rotation. Adapters that support caller-driven rotation
+   * accept `newValue`; provider-driven rotation (a secret manager's own
+   * rotation workflow) ignores it and returns the new version once the
+   * provider workflow completes. Emits a `secret-rotated` event.
+   */
+  rotate(input: SecretRotateInput): Promise<Result<SecretRotateOutcome, SecretError>>;
+
+  /**
+   * Revoke a secret. Retains the record (soft-delete) so audit trails
+   * remain resolvable; adapters MUST return `null` from `get` /
+   * `resolve` for revoked secrets. `hard: true` performs irreversible
+   * destroy for GDPR right-to-erasure. Emits a `secret-revoked` event.
+   */
+  revoke(input: SecretRevokeInput): Promise<Result<SecretRevokeOutcome, SecretError>>;
+}
+
+// -------------------- record types --------------------
+
+export interface SecretRecord {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly currentVersion: number;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly revokedAt?: string;
+  readonly revokeReason?: string;
+  readonly tags?: Readonly<Record<string, string>>;
+  readonly rotationDueAt?: string;
+}
+
+export interface SecretVersionRecord {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly versionId: number;
+  readonly createdAt: string;
+  /**
+   * Always `null` from `getVersion` / `listVersions`; plaintext comes only
+   * from `resolve` (`SecretResolveOutcome.value`).
+   */
+  readonly value: string | null;
+  readonly revokedAt?: string;
+}
+
+// -------------------- inputs --------------------
+
+export interface SecretListInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  readonly namePrefix?: string;
+  readonly tagFilter?: Readonly<Record<string, string>>;
+  readonly includeRevoked?: boolean;
+}
+
+export interface SecretListPage {
+  readonly data: readonly SecretRecord[];
+  readonly nextCursor?: Cursor;
+}
+
+export interface SecretGetInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+}
+
+export interface SecretResolveInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly version?: number;
+  readonly resolveContext: ResolveContext;
+}
+
+/**
+ * Uniform across `EnvBinding.resolve` + `SecretBinding.resolve`.
+ * Names the caller of the resolution for audit-emit attribution.
+ *
+ * Declared here (rather than in a separate module) because the
+ * `SecretBinding` interface is the larger of the two — env-binding.ts
+ * imports the type back from this module to keep the ownership flow
+ * one-directional (env → secrets, not both).
+ */
+export interface ResolveContext {
+  readonly runId?: string;
+  readonly deploymentId?: string;
+  readonly nodeId?: string;
+  readonly caller: 'dispatch' | 'deploy-sync' | 'admin-cli' | 'boot-bridge';
+}
+
+export interface SecretResolveOutcome {
+  readonly name: string;
+  readonly versionId: number;
+  readonly value: string;
+}
+
+export interface SecretGetVersionInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly versionId: number;
+}
+
+export interface SecretListVersionsInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+}
+
+export interface SecretVersionPage {
+  readonly data: readonly SecretVersionRecord[];
+  readonly nextCursor?: Cursor;
+}
+
+export interface SecretSetInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly value: string;
+  readonly writeMode: 'create-new' | 'add-version';
+  readonly tags?: Readonly<Record<string, string>>;
+  readonly rotationDueAt?: string;
+  readonly ifVersion?: number;
+  /**
+   * REQUIRED. Called inside the binding's write tx on FRESH insert
+   * (writeMode: 'create-new' → new secret identity). Receives the new
+   * secret's id as the FGA subject id. Returns tuples for
+   * the same tx — typically `tuplesForCreate({kind:'secret', id,
+   * tenantId, scope}, creatorUserId?)`. Not invoked on `add-version`
+   * (identity already exists in FGA). See `AgentPublishInput.enqueueTuples`
+   * for the design rationale.
+   */
+  readonly enqueueTuples: TupleEnqueueHook;
+}
+
+export type SecretSetOutcome =
+  | { readonly kind: 'ok'; readonly record: SecretRecord; readonly versionId: number }
+  | { readonly kind: 'already-exists'; readonly record: SecretRecord }
+  | { readonly kind: 'version-conflict'; readonly currentVersion: number }
+  | { readonly kind: 'error'; readonly code: string; readonly message: string };
+
+export interface SecretRotateInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly newValue?: string;
+  readonly revokeOldAfterMs?: number;
+}
+
+/**
+ * Discriminated `SecretRotateOutcome`.
+ *
+ * Sync providers (stores that write the new version immediately)
+ * return `{ kind: 'ok', newVersionId, oldVersionId, oldVersionRevokedAt? }`
+ * inline. The `/v1/secrets` HTTP route translates this to a 201
+ * response.
+ *
+ * Async providers (a secret manager whose rotation workflow completes
+ * later) return `{ kind: 'rotation-pending', resumeToken, provider }`.
+ * The HTTP route mints a `rotationId`, records it in the caller-plugged
+ * `RotationStatusStore`, and returns 202 with `{ rotationId, statusUrl,
+ * eventsUrl }`. `resumeToken` is the provider-native handle a
+ * background process uses to poll the async workflow to terminal.
+ */
+export type SecretRotateOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly newVersionId: number;
+      readonly oldVersionId: number;
+      readonly oldVersionRevokedAt?: string;
+    }
+  | {
+      readonly kind: 'rotation-pending';
+      readonly resumeToken: string;
+      readonly provider: string;
+    };
+
+export interface SecretRevokeInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly hard?: boolean;
+  readonly reason?: string;
+}
+
+export interface SecretRevokeOutcome {
+  readonly revoked: boolean;
+  readonly hard: boolean;
+}
+
+export type SecretError =
+  | { readonly code: 'secret-not-found'; readonly message: string; readonly name: string }
+  | { readonly code: 'secret-revoked'; readonly message: string; readonly name: string }
+  | {
+      readonly code: 'secret-version-not-found';
+      readonly message: string;
+      readonly name: string;
+      readonly versionId: number;
+    }
+  | {
+      readonly code: 'secret-encryption-failed';
+      readonly message: string;
+      readonly cause?: unknown;
+    }
+  | {
+      readonly code: 'secret-decryption-failed';
+      readonly message: string;
+      readonly cause?: unknown;
+    }
+  | {
+      readonly code: 'secret-provider-unavailable';
+      readonly message: string;
+      readonly cause?: unknown;
+    }
+  | {
+      readonly code: 'secret-provider-unauthorized';
+      readonly message: string;
+      readonly cause?: unknown;
+    }
+  | {
+      readonly code: 'secret-provider-rate-limited';
+      readonly message: string;
+      readonly retryAfterMs?: number;
+    }
+  | {
+      readonly code: 'secret-write-conflict';
+      readonly message: string;
+      readonly currentVersion: number;
+    }
+  | { readonly code: 'secret-store-error'; readonly message: string; readonly cause?: unknown };