@clearance/management 0.1.4

package/dist/index.d.mts

@@ -0,0 +1,2815 @@
+import { ClearanceAuthBundle } from "@clearance/auth";
+import { createServer } from "node:http";
+
+//#region src/types/resources.d.ts
+type ResourceId = string;
+interface Project {
+  id: ResourceId;
+  name: string;
+  slug: string;
+  createdAt: string;
+  updatedAt: string;
+}
+interface Environment {
+  id: ResourceId;
+  projectId: ResourceId;
+  name: string;
+  slug: string;
+  kind: "development" | "preview" | "production";
+  createdAt: string;
+  updatedAt: string;
+}
+interface Principal {
+  id: ResourceId;
+  projectId: ResourceId;
+  environmentId: ResourceId;
+  email: string;
+  name: string;
+  status: "active" | "disabled" | "deleted";
+  externalId?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+interface Organization {
+  id: ResourceId;
+  projectId: ResourceId;
+  environmentId: ResourceId;
+  name: string;
+  slug: string;
+  status: "active" | "archived";
+  externalId?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+interface Membership {
+  id: ResourceId;
+  organizationId: ResourceId;
+  principalId: ResourceId;
+  role: string;
+  status: "active" | "invited" | "removed";
+  source: "manual" | "scim" | "sso" | "import";
+  createdAt: string;
+  updatedAt: string;
+}
+/**
+ * Authorization role definition (project/environment scoped).
+ * Built-in roles are virtual system definitions; custom roles are persisted.
+ * Optional organizationId binds a custom role to one organization.
+ * Optional status defaults to active when omitted (legacy snapshots).
+ */
+interface CustomRole {
+  id: ResourceId;
+  projectId: ResourceId;
+  environmentId: ResourceId;
+  name: string;
+  /** Lowercase unique key within project+environment */
+  slug: string;
+  description?: string;
+  /** Normalized, deduplicated, stably ordered permission strings (resource:action) */
+  permissions: string[];
+  kind: "built_in" | "custom";
+  /** When set, role may only be assigned within this organization */
+  organizationId?: ResourceId;
+  /** active (default) | disabled | archived — only active roles are assignable */
+  status?: "active" | "disabled" | "archived";
+  createdAt: string;
+  updatedAt: string;
+}
+type IdentityProtocol = "saml" | "oidc" | "password" | "passkey" | "social";
+interface IdentityConnection {
+  id: ResourceId;
+  organizationId: ResourceId;
+  protocol: IdentityProtocol;
+  provider: string;
+  status: "draft" | "testing" | "active" | "disabled";
+  domains: string[];
+  issuer?: string;
+  audience?: string;
+  metadataUrl?: string;
+  clientId?: string;
+  /** Write-only secret fingerprint after create */
+  clientSecretFingerprint?: string;
+  /**
+   * Versioned AEAD envelope for client secret. Write-only — never expose on
+   * public/domain list responses (use publicIdentityConnection).
+   */
+  clientSecretEncrypted?: string;
+  /** Key id used for clientSecretEncrypted (rotation metadata). */
+  clientSecretKeyId?: string;
+  /** Public IdP SAML endpoint and signing certificate used by the runtime. */
+  samlEntryPoint?: string;
+  samlCertificate?: string;
+  samlCertificateFingerprint?: string;
+  certificateFingerprint?: string;
+  attributeMapping: Record<string, string>;
+  createdAt: string;
+  updatedAt: string;
+}
+interface DirectoryConnection {
+  id: ResourceId;
+  organizationId: ResourceId;
+  provider: string;
+  status: "draft" | "testing" | "active" | "disabled";
+  endpoint: string;
+  bearerTokenFingerprint?: string;
+  /**
+   * Versioned AEAD envelope for SCIM bearer. Write-only — strip from public responses.
+   */
+  bearerTokenEncrypted?: string;
+  bearerTokenKeyId?: string;
+  deprovisioningPolicy: "disable" | "delete" | "suspend";
+  createdAt: string;
+  updatedAt: string;
+}
+/**
+ * Persisted setup capability: digest only (never raw token).
+ * Single-use, scoped to project/environment/organization + action.
+ *
+ * Completion state machine (durable fields only):
+ * - available: useCount < maxUses, !redeemedAt, !revokedAt, no active reservation
+ * - reserved: reservedAt + reservationId + reservationExpiresAt (in-progress lease)
+ * - redeemed: useCount >= maxUses and redeemedAt set (terminal; never reopen)
+ * - revoked: revokedAt set
+ *
+ * Raw capability tokens are never stored. Reservation ids are opaque leases,
+ * not the customer token.
+ */
+interface SetupCapability {
+  id: ResourceId;
+  /** SHA-256 hex digest of the capability token */
+  digest: string;
+  kind: "sso" | "scim";
+  action: "setup";
+  resourceType: "organization";
+  resourceId: ResourceId;
+  organizationId: ResourceId;
+  projectId: ResourceId;
+  environmentId: ResourceId;
+  expiresAt: string;
+  maxUses: number;
+  useCount: number;
+  revokedAt?: string;
+  redeemedAt?: string;
+  /**
+   * In-progress completion lease. Bound with reservationExpiresAt so a crashed
+   * holder does not permanently burn the capability. Cleared on commit/release.
+   */
+  reservedAt?: string;
+  /**
+   * Opaque lease / setup-attempt id. Derived from the capability digest so the
+   * same attempt identity is reused after lease expiry (durable provision
+   * reconcile). Never the raw capability token.
+   */
+  reservationId?: string;
+  /** When the reservation lease ends and another attempt may re-reserve. */
+  reservationExpiresAt?: string;
+  createdAt: string;
+}
+interface AuditEvent {
+  id: ResourceId;
+  correlationId: string;
+  projectId?: ResourceId;
+  environmentId?: ResourceId;
+  organizationId?: ResourceId;
+  actor: string;
+  action: string;
+  subjectType: string;
+  subjectId?: string;
+  outcome: "success" | "failure" | "pending";
+  source: "cli" | "console" | "api" | "system" | "migration" | "sso" | "scim";
+  message: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+}
+type ConformanceMode = "simulation" | "live";
+interface DiagnosticTrace {
+  id: ResourceId;
+  correlationId: string;
+  projectId?: ResourceId;
+  environmentId?: ResourceId;
+  organizationId?: ResourceId;
+  connectionId?: ResourceId;
+  subsystem: "sso" | "scim" | "email" | "webhook" | "session" | "migration" | "deploy" | "doctor";
+  stage: string;
+  outcome: "pass" | "fail" | "warn";
+  /**
+   * simulation = fixture/lab path (not live IdP/directory conformance)
+   * live = exercised against a real external system
+   */
+  mode?: ConformanceMode;
+  cause?: string;
+  causeConfidence?: number;
+  owner?: "customer" | "application" | "clearance";
+  remediation?: string;
+  redactedRequest?: Record<string, unknown>;
+  redactedResponse?: Record<string, unknown>;
+  checks?: Array<{
+    name: string;
+    pass: boolean;
+    detail?: string;
+  }>;
+  createdAt: string;
+}
+interface ReadinessCheck {
+  id: string;
+  name: string;
+  status: "pass" | "fail" | "warn" | "skip";
+  detail: string;
+  fingerprint?: string;
+  /** When true, a pass does not imply live production conformance */
+  simulation?: boolean;
+}
+interface ReadinessReport {
+  id: ResourceId;
+  organizationId: ResourceId;
+  generatedAt: string;
+  checks: ReadinessCheck[];
+  overall: "ready" | "blocked" | "attention";
+  /** Explicit: overall ready never means live IdP/SCIM certification from synthetic checks */
+  conformance: {
+    mode: ConformanceMode;
+    liveCertified: false | true;
+    note: string;
+  };
+  remainingCustomerActions: string[];
+  signature: string;
+}
+interface MigrationPlan {
+  id: ResourceId;
+  source: "legacy";
+  /** Immutable operator scope that owns this migration plan. */
+  readonly projectId: ResourceId;
+  readonly environmentId: ResourceId;
+  status: "planned" | "running" | "verified" | "rolled_back" | "failed";
+  counts: Record<string, number>;
+  /** Stable fixture identity and last durable import checkpoint for safe resume/audit. */
+  fixtureChecksum: string;
+  checkpoint: {
+    phase: "planned" | "dry_run" | "imported" | "verified" | "failed" | "rolled_back";
+    source: "legacy";
+    fixtureChecksum: string;
+    counts: Record<string, number>;
+    wouldCreate: Record<string, number>;
+    idempotent: Record<string, number>;
+  };
+  createdResourceIds?: {
+    users: ResourceId[];
+    organizations: ResourceId[];
+    memberships: ResourceId[];
+  };
+  /** Exact runtime rows created by the coordinated Postgres importer. */
+  createdRuntimeResourceIds?: {
+    users: ResourceId[];
+    organizations: ResourceId[];
+    memberships: ResourceId[];
+  };
+  /** Identity and relationship fields that must still match before exact rollback. */
+  rollbackResourceState?: {
+    management: {
+      users: Array<{
+        id: ResourceId;
+        projectId: ResourceId;
+        environmentId: ResourceId;
+        email: string;
+        name: string;
+        status: Principal["status"];
+        externalId?: string;
+        updatedAt: string;
+      }>;
+      organizations: Array<{
+        id: ResourceId;
+        projectId: ResourceId;
+        environmentId: ResourceId;
+        name: string;
+        slug: string;
+        status: Organization["status"];
+        externalId?: string;
+        updatedAt: string;
+      }>;
+      memberships: Array<{
+        id: ResourceId;
+        organizationId: ResourceId;
+        principalId: ResourceId;
+        role: string;
+        status: Membership["status"];
+        source: Membership["source"];
+        updatedAt: string;
+      }>;
+    };
+    runtime: {
+      users: Array<{
+        id: ResourceId;
+        email: string;
+        name: string;
+        emailVerified: boolean;
+        image: string | null;
+        banned: boolean;
+        banReason: string | null;
+        updatedAt: string;
+      }>;
+      organizations: Array<{
+        id: ResourceId;
+        name: string;
+        slug: string;
+        logo: string | null;
+        metadata: string | null;
+      }>;
+      memberships: Array<{
+        id: ResourceId;
+        organizationId: ResourceId;
+        principalId: ResourceId;
+        role: string;
+      }>;
+    };
+  };
+  steps: Array<{
+    name: string;
+    status: "pending" | "done" | "failed" | "skipped";
+    detail?: string;
+  }>;
+  createdAt: string;
+  updatedAt: string;
+}
+interface BackupRecord {
+  id: ResourceId;
+  path: string;
+  createdAt: string;
+  checksum: string;
+  resourceCounts: Record<string, number>;
+  verified: boolean;
+}
+interface SessionRecord {
+  id: ResourceId;
+  principalId: ResourceId;
+  environmentId: ResourceId;
+  status: "active" | "revoked";
+  createdAt: string;
+  revokedAt?: string;
+}
+/** Digest-only API key record. The raw secret is returned once at creation only. */
+interface ApiKey {
+  id: ResourceId;
+  projectId: ResourceId;
+  environmentId: ResourceId;
+  name: string;
+  /** Normalized, sorted authorization scopes. */
+  scopes: string[];
+  /** SHA-256 hex digest of the raw API key; never expose in public views. */
+  digest: string;
+  /** Safe non-secret identifier derived from the key material. */
+  prefix: string;
+  /** Short digest fingerprint for operator correlation. */
+  fingerprint: string;
+  status: "active" | "revoked";
+  createdAt: string;
+  updatedAt: string;
+  revokedAt?: string;
+  replacedById?: string;
+}
+interface DoctorCheck {
+  id: string;
+  name: string;
+  status: "pass" | "fail" | "warn";
+  detail: string;
+  remediation?: string;
+}
+interface DataStoreSnapshot {
+  version: number;
+  releaseVersion: string;
+  projects: Project[];
+  environments: Environment[];
+  principals: Principal[];
+  organizations: Organization[];
+  memberships: Membership[];
+  identityConnections: IdentityConnection[];
+  directoryConnections: DirectoryConnection[];
+  /** Custom (operator-defined) roles only — built-ins are virtual */
+  roles: CustomRole[];
+  events: AuditEvent[];
+  traces: DiagnosticTrace[];
+  readinessReports: ReadinessReport[];
+  migrations: MigrationPlan[];
+  backups: BackupRecord[];
+  sessions: SessionRecord[];
+  /** API-key digests only; raw secrets are never snapshotted. */
+  apiKeys: ApiKey[];
+  /** Capability digests for SSO/SCIM setup links (no raw tokens) */
+  setupLinks: SetupCapability[];
+  meta: {
+    initializedAt?: string;
+    schemaVersion: number;
+    config: Record<string, string>;
+  };
+}
+//#endregion
+//#region src/store/types.d.ts
+/**
+ * Management control-plane store.
+ * Json backend is for local dev without DATABASE_URL.
+ * Postgres backend is the single transactional source of truth when DATABASE_URL is set.
+ *
+ * Cross-process safety (Postgres): mutations are transactionally replayed against a
+ * row-locked snapshot with a monotonically increasing revision. Long-lived processes
+ * must call refresh() before reads so CLI writes are visible to a running API.
+ */
+interface ManagementStore {
+  /** Local path used for file-backed stores and backup directory resolution */
+  readonly path: string;
+  readonly backend: "json" | "postgres";
+  get snapshot(): DataStoreSnapshot;
+  load(): DataStoreSnapshot;
+  save(): void;
+  /** Flush pending durable writes (no-op for json; await for postgres) */
+  ready(): Promise<void>;
+  /**
+   * Reload from durable backend when another process may have written.
+   * Json re-reads the file; Postgres compares revision and replaces local cache.
+   */
+  refresh(): Promise<void>;
+  replace(snapshot: DataStoreSnapshot): void;
+  /**
+   * Queue a mutation. For Postgres the function is replayed inside
+   * BEGIN…SELECT FOR UPDATE…COMMIT so concurrent writers merge by replaying
+   * ops rather than last-write-wins full snapshot overwrite.
+   * Await ready() before relying on snapshot for subsequent reads.
+   */
+  mutate(fn: (data: DataStoreSnapshot) => void): DataStoreSnapshot;
+  /** Execute against the latest durable draft and resolve only after commit. */
+  mutateDurable<T>(fn: (data: DataStoreSnapshot) => T): Promise<T>;
+  /**
+   * Postgres only: one transaction covering management snapshot (+ uniqueness +
+   * audit via the mutator) and arbitrary runtime SQL on the same connection.
+   * JsonStore does not implement this — callers must use management-only paths.
+   */
+  mutateCoordinated?<T>(fn: (ctx: {
+    data: DataStoreSnapshot;
+    query: (sql: string, params?: unknown[]) => Promise<{
+      rows: Record<string, unknown>[];
+      rowCount: number | null;
+    }>;
+  }) => Promise<T> | T): Promise<T>;
+  checksum(): string;
+  resourceCounts(): Record<string, number>;
+}
+declare function isManagementStore(value: unknown): value is ManagementStore;
+//#endregion
+//#region src/store/json-store.d.ts
+declare const STORE_SCHEMA_VERSION = 1;
+declare const CLEARANCE_RELEASE_VERSION = "0.1.4";
+declare function emptySnapshot(config?: Record<string, string>): DataStoreSnapshot;
+/** Normalize older snapshots missing newer collections. */
+declare function normalizeSnapshot(data: DataStoreSnapshot): DataStoreSnapshot;
+declare function defaultDataPath(): string;
+/** File-backed store for local development without DATABASE_URL. */
+declare class JsonStore implements ManagementStore {
+  readonly backend: "json";
+  readonly path: string;
+  private data;
+  constructor(path?: string);
+  load(): DataStoreSnapshot;
+  save(): void;
+  ready(): Promise<void>;
+  /** Re-read file so another process's writes are visible (local multi-process). */
+  refresh(): Promise<void>;
+  get snapshot(): DataStoreSnapshot;
+  replace(snapshot: DataStoreSnapshot): void;
+  /**
+   * Apply mutation on a draft so a thrown validation error does not leave
+   * a half-applied in-memory snapshot (atomic validation+mutation+audit).
+   */
+  mutate(fn: (data: DataStoreSnapshot) => void): DataStoreSnapshot;
+  mutateDurable<T>(fn: (data: DataStoreSnapshot) => T): Promise<T>;
+  checksum(): string;
+  resourceCounts(): Record<string, number>;
+}
+declare function newId(prefix: string): string;
+declare function nowIso(): string;
+declare function fingerprint(value: string): string;
+declare function correlationId(): string;
+//#endregion
+//#region src/store/pg-store.d.ts
+declare class PgStore implements ManagementStore {
+  readonly backend: "postgres";
+  readonly path: string;
+  private data;
+  private revision;
+  private pool;
+  private table;
+  private emailUniqueTable;
+  private slugUniqueTable;
+  private idempotencyTable;
+  private pending;
+  /** Set when a queued write fails; rethrown from ready() so the chain never rejects. */
+  private writeError;
+  private initialized;
+  constructor(databaseUrl: string, opts?: {
+    backupDir?: string;
+    tableName?: string;
+  });
+  /** Ensure schema + load snapshot. Call before first use. */
+  init(): Promise<this>;
+  load(): DataStoreSnapshot;
+  get snapshot(): DataStoreSnapshot;
+  /** Monotonic revision of the last known durable snapshot (test/debug). */
+  get currentRevision(): number;
+  save(): void;
+  ready(): Promise<void>;
+  /**
+   * Pull latest durable snapshot if another process advanced the revision.
+   * Safe to call on every API request; no-op when revision is current.
+   */
+  refresh(): Promise<void>;
+  replace(snapshot: DataStoreSnapshot): void;
+  mutate(fn: (data: DataStoreSnapshot) => void): DataStoreSnapshot;
+  mutateDurable<T>(fn: (data: DataStoreSnapshot) => T): Promise<T>;
+  /**
+   * Single Postgres transaction: lock management snapshot, run caller SQL
+   * (runtime user/session/account tables) + snapshot mutator, enforce
+   * uniqueness indexes, commit. Full ROLLBACK on any throw — never returns
+   * success when runtime and management diverge.
+   */
+  mutateCoordinated<T>(fn: (ctx: {
+    data: DataStoreSnapshot;
+    query: (sql: string, params?: unknown[]) => Promise<{
+      rows: Record<string, unknown>[];
+      rowCount: number | null;
+    }>;
+  }) => Promise<T> | T): Promise<T>;
+  checksum(): string;
+  resourceCounts(): Record<string, number>;
+  destroy(): Promise<void>;
+  /**
+   * Read a stored Idempotency-Key replay record. Expired rows are treated as
+   * absent (TTL is enforced on read as well as by opportunistic cleanup).
+   */
+  getIdempotencyRecord(scopeKey: string, key: string): Promise<{
+    fingerprint: string;
+    status: number;
+    contentType: string;
+    body: string;
+  } | null>;
+  /**
+   * Store an Idempotency-Key replay record with a TTL. Opportunistically
+   * deletes expired rows first (the table stays small; expiry never touches
+   * the snapshot). ON CONFLICT DO NOTHING: the first committed responder wins
+   * under a same-key race.
+   */
+  putIdempotencyRecord(record: {
+    scopeKey: string;
+    key: string;
+    fingerprint: string;
+    status: number;
+    contentType: string;
+    body: string;
+    ttlMs: number;
+  }): Promise<void>;
+  /**
+   * Enqueue a mutation that will be transactionally replayed against the
+   * row-locked latest snapshot (not applied only to a stale process-local copy).
+   * The chain never rejects (errors are stashed and rethrown from ready()) so
+   * concurrent writers cannot strand later ops or emit unhandledRejection.
+   */
+  private queueWrite;
+  private transactReplay;
+  private transactMutation;
+  private transactCoordinated;
+  /**
+   * Rebuild uniqueness tables from snapshot inside the open transaction.
+   * Primary keys enforce same-email / same-slug within project+environment.
+   * Concurrent writers serialize on snapshot FOR UPDATE; app checks catch
+   * duplicates first, and these constraints fail closed as a second layer.
+   */
+  private syncUniqueness;
+  /** Initial insert path used only from init when the row is missing. */
+  private persistLocked;
+}
+declare function createPgStore(databaseUrl: string, opts?: {
+  backupDir?: string;
+  tableName?: string;
+}): Promise<PgStore>;
+declare function pgStoreId(): string;
+//#endregion
+//#region src/store/create-store.d.ts
+type CreateStoreOptions = {
+  /** Explicit file path for JSON backend */dataPath?: string; /** Force backend; default chooses postgres when DATABASE_URL is set */
+  backend?: "json" | "postgres" | "auto";
+  databaseUrl?: string;
+};
+/**
+ * Open the management store.
+ * - DATABASE_URL set → Postgres is the single transactional source of truth
+ * - otherwise → local JSON file (developer quick path)
+ */
+declare function createManagementStore(opts?: CreateStoreOptions): Promise<ManagementStore>;
+//#endregion
+//#region src/services/errors.d.ts
+declare class ClearanceError extends Error {
+  readonly code: string;
+  readonly stage: string;
+  readonly retryable: boolean;
+  readonly remediation: string;
+  readonly status: number;
+  constructor(opts: {
+    code: string;
+    message: string;
+    stage: string;
+    retryable?: boolean;
+    remediation?: string;
+    status?: number;
+  });
+  toJSON(): {
+    error: {
+      code: string;
+      message: string;
+      stage: string;
+      retryable: boolean;
+      remediation: string;
+    };
+  };
+}
+declare function isClearanceError(err: unknown): err is ClearanceError;
+//#endregion
+//#region src/services/config.d.ts
+type ConfigRecord = Record<string, string>;
+declare function isSecretLikeConfigKey(key: string): boolean;
+declare function isSecretLikeConfigEntry(key: string, value: string): boolean;
+/** Parse the deliberately small config-file grammar while detecting duplicate keys. */
+declare function parseConfigJson(input: string): ConfigRecord;
+declare function validateConfig(store: ManagementStore, config: ConfigRecord): ConfigRecord;
+declare function validateCurrentConfig(store: ManagementStore): ConfigRecord;
+declare function publicConfig(config: ConfigRecord, key?: string): {
+  config: ConfigRecord;
+  redactedKeys: string[];
+};
+declare function setConfig(store: ManagementStore, key: string, value: string): {
+  changed: boolean;
+  config: ConfigRecord;
+};
+declare function diffConfig(current: ConfigRecord, candidate: ConfigRecord): {
+  added: string[];
+  changed: string[];
+  removed: string[];
+};
+//#endregion
+//#region src/services/redact.d.ts
+declare function redactValue(value: unknown, keyHint?: string): unknown;
+declare function redactRecord(input: Record<string, unknown> | undefined | null): Record<string, unknown> | undefined;
+/** Keys that must never appear on connection/audit records */
+declare const WRITE_ONLY_SECRET_FIELDS: readonly ["clientSecret", "bearerToken", "password", "token", "_token", "scimToken", "clientSecretEncrypted", "bearerTokenEncrypted"];
+/** Public domain view of SSO connection — encrypted material stripped. */
+declare function publicIdentityConnection(conn: IdentityConnection): Omit<IdentityConnection, "clientSecretEncrypted" | "clientSecretKeyId"> & {
+  hasClientSecret: boolean;
+};
+/** Public domain view of SCIM connection — encrypted material stripped. */
+declare function publicDirectoryConnection(conn: DirectoryConnection): Omit<DirectoryConnection, "bearerTokenEncrypted" | "bearerTokenKeyId"> & {
+  hasBearerToken: boolean;
+};
+//#endregion
+//#region src/services/secrets.d.ts
+/**
+ * Production secret policy for control plane and auth runtime.
+ */
+/** Known-insecure defaults that production must refuse. */
+declare const FORBIDDEN_DEFAULT_SECRETS: readonly ["dev-secret-change-me", "dev-secret-change-me-please-32chars!!", "secret", "local-compose-secret-change-me-32", "test-secret-value-32-characters", "test-secret-value-that-is-long-enough", "test-secret-value-that-is-long-enough-32", "change-me", "password", "clearance", "clearance-secret"];
+declare function isForbiddenDefaultSecret(secret: string | undefined | null): boolean;
+declare function assertProductionSecret(secret: string | undefined, label?: string): void;
+declare function requireOperatorToken(): string;
+/**
+ * Production startup guard for credential encryption key material.
+ * Call from management API / console when NODE_ENV=production.
+ */
+declare function assertProductionCredentialKey(env?: NodeJS.ProcessEnv): void;
+declare function parseCorsOrigins(): string[];
+//#endregion
+//#region src/services/credentials.d.ts
+type CredentialKeyring = {
+  currentKeyId: string; /** keyId → 32-byte key material */
+  keys: Map<string, Buffer>;
+};
+type EncryptedCredential = {
+  /** Versioned AEAD envelope (never the plaintext) */ciphertext: string;
+  keyId: string; /** Short fingerprint of plaintext for comparison without disclosure */
+  fingerprint: string;
+};
+declare function fingerprintCredential(value: string): string;
+/**
+ * Resolve keyring from environment.
+ * - CLEARANCE_CREDENTIAL_KEY + CLEARANCE_CREDENTIAL_KEY_ID (required outside dev/test)
+ * - Optional CLEARANCE_CREDENTIAL_PREVIOUS_KEY / CLEARANCE_CREDENTIAL_PREVIOUS_KEY_ID for rotation
+ * - CLEARANCE_CREDENTIAL_KEYS_JSON: {"kid":"secret",...} with CLEARANCE_CREDENTIAL_KEY_ID as current
+ */
+declare function resolveCredentialKeyring(env?: NodeJS.ProcessEnv): CredentialKeyring | null;
+declare function isDevelopmentLike(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Fail closed outside development/test when credential key is missing or weak.
+ */
+declare function assertCredentialKeyConfigured(env?: NodeJS.ProcessEnv): CredentialKeyring;
+declare function getCredentialKeyring(env?: NodeJS.ProcessEnv): CredentialKeyring;
+declare function encryptCredential(plaintext: string, ring?: CredentialKeyring): EncryptedCredential;
+declare function parseCredentialEnvelope(envelope: string): {
+  version: 1;
+  keyId: string;
+  iv: Buffer;
+  tag: Buffer;
+  ct: Buffer;
+};
+declare function decryptCredential(envelope: string, ring?: CredentialKeyring): string;
+/** Re-encrypt under the current key id (rotation). */
+declare function rotateCredential(envelope: string, ring?: CredentialKeyring): EncryptedCredential;
+/** True when value looks like our envelope (not plaintext). */
+declare function isCredentialEnvelope(value: string | undefined | null): boolean;
+//#endregion
+//#region src/services/audit.d.ts
+declare const AUDIT_MAX_EVENTS_DEFAULT = 5000;
+declare const AUDIT_MAX_EVENTS_MIN = 10;
+declare const AUDIT_MAX_EVENTS_MAX = 1000000;
+declare const AUDIT_PRUNED_ACTION = "system.audit.pruned";
+declare function auditMaxEvents(env?: Record<string, string | undefined>): number;
+type AuditEventInput = Omit<AuditEvent, "id" | "createdAt" | "correlationId"> & {
+  correlationId?: string;
+};
+/** Build a redacted audit event (no secrets/tokens in metadata). */
+declare function buildAuditEvent(input: AuditEventInput): AuditEvent;
+/**
+ * Enforce the retention cap on a snapshot draft (events are newest-first).
+ * Truncation maintains exactly ONE rolling system.audit.pruned marker with a
+ * cumulative droppedCount. A per-prune marker is itself an event that
+ * re-overflows the cap, so the naive version reached ~50% marker density at
+ * steady state and halved effective retention (adversarial finding M3).
+ * Prior markers are extracted (counts carried forward), overflow real events
+ * drop from the tail, and one cumulative marker is reinserted at the head —
+ * never re-triggering itself (no recursion, no cap overshoot).
+ */
+declare function enforceAuditRetention(data: DataStoreSnapshot): void;
+/**
+ * Append an audit event onto a snapshot draft. Use inside the same store.mutate
+ * as the resource mutation so Postgres commits validation+write+audit atomically.
+ */
+declare function appendAuditEvent(data: DataStoreSnapshot, input: AuditEventInput): AuditEvent;
+declare function recordEvent(store: ManagementStore, input: AuditEventInput): AuditEvent;
+//#endregion
+//#region src/services/scope.d.ts
+type ResourceScope = {
+  projectId: string;
+  environmentId: string;
+};
+type ScopedResource = {
+  projectId: string;
+  environmentId: string;
+};
+/**
+ * Resolve the authenticated operator's scope from server configuration + store.
+ * Order:
+ * 1. Explicit opts (tests / internal callers)
+ * 2. CLEARANCE_PROJECT_ID + CLEARANCE_ENV_ID (secure server-side mapping)
+ * 3. store.meta.config after init
+ * 4. Sole project/environment pair in the store (local single-project profile)
+ *
+ * Rejects when scope cannot be determined — never invents foreign scope.
+ */
+declare function resolveOperatorScope(store: ManagementStore, opts?: Partial<ResourceScope>): ResourceScope;
+/**
+ * Optional client header consistency check. Headers never select scope —
+ * if present they must equal the principal-derived scope.
+ */
+declare function assertClientScopeHeaders(principal: ResourceScope, headerProject?: string | null, headerEnv?: string | null): void;
+/**
+ * Fail closed for cross-scope resource access — same error as missing so
+ * foreign resources are not revealed.
+ */
+declare function assertResourceInScope(resource: ScopedResource | null | undefined, scope: ResourceScope, opts: {
+  code: string;
+  stage: string;
+  label?: string;
+}): asserts resource is ScopedResource;
+declare function scopeFilter(scope: ResourceScope): (r: ScopedResource) => boolean;
+//#endregion
+//#region src/services/pagination.d.ts
+type PageSurface = "users" | "organizations" | "events" | "sessions";
+type PageOrder = "asc" | "desc";
+type PageCursorKey = {
+  createdAt: string;
+  id: string;
+};
+declare function encodePageCursor(surface: PageSurface, key: PageCursorKey): string;
+/**
+ * Decode + validate an opaque cursor. Fail-closed: anything that is not a
+ * well-formed cursor for this surface throws CURSOR_INVALID (garbage base64,
+ * non-JSON, wrong shape, wrong version, or a cursor minted for another
+ * surface). Returns undefined when no cursor was supplied.
+ */
+declare function decodePageCursor(raw: string | undefined | null, surface: PageSurface, stage: string): PageCursorKey | undefined;
+type ResourcePage<T> = {
+  items: T[]; /** Opaque cursor for the next page; null when this page is the last. */
+  nextCursor: string | null;
+};
+/**
+ * Keyset-paginate an already-filtered snapshot array. Items are sorted into
+ * the documented order for the surface, the page starts strictly after the
+ * cursor key (when present), and nextCursor is emitted only when more items
+ * remain.
+ */
+declare function paginateByCreatedAt<T extends {
+  id: string;
+  createdAt: string;
+}>(items: T[], opts: {
+  surface: PageSurface;
+  order: PageOrder;
+  limit: number;
+  cursor?: PageCursorKey;
+}): ResourcePage<T>;
+/**
+ * Fail-closed page-size validation shared by paginated list services.
+ * NaN / non-integers / out-of-range values raise the caller's stable code.
+ */
+declare function normalizePageLimit(limit: number | undefined, spec: {
+  stage: string;
+  code: string;
+  defaultValue: number;
+  maximum: number;
+}): number;
+//#endregion
+//#region src/services/idempotency.d.ts
+declare const IDEMPOTENCY_DEFAULT_TTL_MS: number;
+type IdempotencyRecord = {
+  /** Route+method scope, e.g. "POST /v1/users" */scopeKey: string; /** Client-supplied Idempotency-Key header value */
+  key: string; /** sha256 of scopeKey + raw request body — detects key reuse conflicts */
+  fingerprint: string;
+  status: number;
+  contentType: string;
+  body: string;
+};
+interface IdempotencyBackend {
+  readonly kind: "postgres" | "memory";
+  get(scopeKey: string, key: string): Promise<IdempotencyRecord | null>;
+  put(record: IdempotencyRecord): Promise<void>;
+}
+/**
+ * Resolve the replay TTL. CLEARANCE_IDEMPOTENCY_TTL_MS overrides the 24h
+ * default (fail-closed on garbage — an unparseable TTL must not silently
+ * become "keys never expire" or "keys never match").
+ */
+declare function resolveIdempotencyTtlMs(env?: Record<string, string | undefined>): number;
+/** Fail-closed Idempotency-Key header validation (visible ASCII, 1–200 chars). */
+declare function assertIdempotencyKeyValid(key: string): void;
+/** Deterministic request fingerprint: same route+method+body ⇒ same digest. */
+declare function fingerprintIdempotentRequest(scopeKey: string, rawBody: string): string;
+/** Structured 409 for Idempotency-Key reuse with a different payload. */
+declare function idempotencyConflictError(scopeKey: string): ClearanceError;
+/**
+ * Pick the idempotency backend for a management store: the Postgres companion
+ * table when the store is PgStore, otherwise the process-local in-memory map.
+ */
+declare function createIdempotencyBackend(store: ManagementStore, opts?: {
+  ttlMs?: number;
+  now?: () => number;
+}): IdempotencyBackend;
+//#endregion
+//#region src/services/members.d.ts
+type MembershipSource = Membership["source"];
+type MembershipActorSource = "cli" | "console" | "api" | "import" | "scim" | "system";
+/**
+ * Fail closed when the target is the sole active owner and the mutation would
+ * remove ownership (demote or remove). At least one owner is required.
+ */
+declare function assertOwnerInvariant(data: {
+  memberships: Membership[];
+}, opts: {
+  organizationId: string;
+  membership: Membership; /** Next role after update; omit for remove */
+  nextRole?: string;
+  stage: string;
+}): void;
+declare function listMembers(store: ManagementStore, organizationId: string, opts?: {
+  scope?: ResourceScope;
+  includeRemoved?: boolean;
+}): Membership[];
+declare function inspectMembership(store: ManagementStore, id: string, scope?: ResourceScope): Membership;
+/**
+ * Find active membership by org + principal. Cross-scope ids fail as not found
+ * when scope is provided.
+ */
+declare function findActiveMembership(store: ManagementStore, organizationId: string, principalId: string, scope?: ResourceScope): Membership | undefined;
+/**
+ * Management-only add. Prefer addMemberInAuth when DATABASE_URL + PgStore.
+ * Idempotent: returns existing active membership without a second audit.
+ * Invalid roles fail closed with no write.
+ */
+declare function addMember(store: ManagementStore, input: {
+  organizationId: string;
+  principalId: string;
+  role?: string;
+  source?: MembershipSource;
+  actor?: string;
+  auditSource?: MembershipActorSource;
+  scope?: ResourceScope; /** Force a specific membership id (runtime id preservation) */
+  id?: string;
+}): Membership;
+/**
+ * Update membership role (management-only). Prefer updateMemberInAuth with
+ * DATABASE_URL + PgStore.
+ */
+declare function updateMember(store: ManagementStore, id: string, input: {
+  role: string;
+  actor?: string;
+  auditSource?: MembershipActorSource;
+  scope?: ResourceScope;
+}): Membership;
+/**
+ * Soft-remove membership (management-only). Prefer removeMemberInAuth with
+ * DATABASE_URL + PgStore. Destructive; CLI requires --yes.
+ */
+declare function removeMember(store: ManagementStore, id: string, input?: {
+  actor?: string;
+  auditSource?: MembershipActorSource;
+  scope?: ResourceScope;
+}): Membership;
+/**
+ * Update or remove by organization + principal (CLI convenience).
+ * Fails closed when membership missing (same as inspect).
+ */
+declare function resolveMembershipId(store: ManagementStore, input: {
+  organizationId: string;
+  principalId?: string;
+  membershipId?: string;
+  scope?: ResourceScope;
+}, stage: string): string;
+//#endregion
+//#region src/services/core.d.ts
+/** Validate and normalize a project name without mutating the store. */
+declare function planProjectCreate(input: {
+  name: string;
+}, existingProjects?: Project[]): Pick<Project, "name" | "slug">;
+/** Create an additional project without changing the operator's active scope. */
+declare function createProject(store: ManagementStore, input: {
+  name: string;
+  actor?: string;
+  source?: "cli" | "console" | "api";
+}): Project;
+declare function initProject(store: ManagementStore, input: {
+  name: string;
+  environment?: string;
+  actor?: string;
+  source?: "cli" | "console" | "api";
+}): {
+  project: Project;
+  environment: Environment;
+};
+declare function listProjects(store: ManagementStore): Project[];
+declare function createEnvironment(store: ManagementStore, input: {
+  projectId: string;
+  name: string;
+  kind?: Environment["kind"];
+  actor?: string;
+}): Environment;
+/** Validate an environment creation request without mutating the store. */
+declare function planEnvironmentCreate(store: ManagementStore, input: {
+  projectId?: string;
+  name: string;
+  kind?: Environment["kind"];
+}): Pick<Environment, "projectId" | "name" | "slug" | "kind">;
+/**
+ * List environments for the operator's project (project-scoped).
+ * Environment rows are not dual-scoped; projectId must match principal project.
+ */
+declare function listEnvironments(store: ManagementStore, filter?: {
+  scope?: ResourceScope;
+}): Environment[];
+type EnvironmentLocalStatus = {
+  /** Whether this environment is the operator's active principal environment */active: boolean;
+  storeBackend: ManagementStore["backend"];
+  storePathPresent: boolean;
+  schemaVersion: number;
+  expectedSchemaVersion: number;
+  releaseVersion: string;
+  initialized: boolean; /** Configuration presence flags only — never secret values */
+  config: {
+    hasClearanceSecret: boolean;
+    hasDatabaseUrl: boolean;
+    hasOperatorToken: boolean;
+    hasCredentialKey: boolean;
+    nodeEnv: string;
+    operatorProjectIdConfigured: boolean;
+    operatorEnvironmentIdConfigured: boolean;
+  };
+  resourceCounts: {
+    principals: number;
+    organizations: number;
+    memberships: number;
+    identityConnections: number;
+    directoryConnections: number;
+    roles: number;
+    sessions: number;
+    events: number;
+  };
+};
+type EnvironmentInspectResult = {
+  environment: Environment;
+  project: Project | null;
+  scope: ResourceScope;
+  local: EnvironmentLocalStatus;
+  correlationId: string;
+};
+/**
+ * Inspect a canonical environment plus truthful local status (no secrets).
+ * Default id is the operator principal environment. Cross-project ids fail closed.
+ */
+declare function inspectEnvironment(store: ManagementStore, id?: string, opts?: {
+  scope?: ResourceScope;
+}): EnvironmentInspectResult;
+type EnvironmentPromoteBlocker = {
+  code: string;
+  message: string;
+  remediation: string;
+};
+type EnvironmentPromotePlanStep = {
+  name: string;
+  status: "planned" | "blocked" | "skipped" | "done";
+  detail?: string;
+};
+type EnvironmentPromoteResult = {
+  dryRun: boolean;
+  applied: boolean;
+  blocked: boolean;
+  idempotent: boolean;
+  wouldChange: boolean;
+  source: Environment;
+  target: Environment;
+  scope: ResourceScope;
+  plan: {
+    action: "env.promote";
+    description: string;
+    resourceCounts: EnvironmentLocalStatus["resourceCounts"];
+    steps: EnvironmentPromotePlanStep[];
+  };
+  blockers: EnvironmentPromoteBlocker[];
+  correlationId: string;
+  auditAction?: "env.promote";
+};
+/**
+ * Plan (and optionally attempt) environment promotion.
+ *
+ * Grounded in existing Environment + scoped resource counts only. The snapshot
+ * has no Deployment resource, so mutating apply always surfaces an explicit
+ * structured blocker rather than inventing deployment state. Dry-run and
+ * confirmed apply both validate inputs, return the same plan shape, and audit
+ * confirmed attempts (including blocked/idempotent outcomes).
+ */
+declare function promoteEnvironment(store: ManagementStore, input: {
+  /** Target environment id or slug (required) */to: string; /** Source environment id or slug; defaults to operator principal environment */
+  from?: string; /** Preview only — default when confirm is not true */
+  dryRun?: boolean; /** Required for a confirmed attempt (CLI --yes). Never invents deploy apply. */
+  confirm?: boolean;
+  scope?: ResourceScope;
+  actor?: string;
+  source?: "cli" | "console" | "api" | "system";
+}): EnvironmentPromoteResult;
+declare function createUser(store: ManagementStore, input: {
+  email: string;
+  name: string; /** Optional stable id (e.g. Clearance runtime user id) */
+  id?: string;
+  projectId?: string;
+  environmentId?: string;
+  externalId?: string;
+  actor?: string;
+  source?: "cli" | "console" | "api" | "import" | "scim";
+}): Principal;
+declare function listUsers(store: ManagementStore, filter?: {
+  environmentId?: string;
+  projectId?: string;
+  status?: string; /** When true (default for scoped callers), require full scope filter */
+  scope?: ResourceScope;
+}): Principal[];
+declare const USERS_LIST_DEFAULT_PAGE_LIMIT = 100;
+declare const USERS_LIST_MAX_PAGE_LIMIT = 1000;
+/**
+ * Cursor-paginated users listing (FOLLOW.md P2.3.1), shared by CLI and API.
+ * Ordering: createdAt ascending, then id ascending (documented keyset — see
+ * pagination.ts for why keyset beats index cursors on the snapshot arrays).
+ * Callers that need the full unpaginated legacy behavior keep using listUsers.
+ */
+declare function listUsersPage(store: ManagementStore, opts?: {
+  scope?: ResourceScope;
+  status?: string;
+  limit?: number; /** Opaque cursor from a previous page's nextCursor (fail-closed). */
+  cursor?: string;
+}): {
+  users: Principal[];
+  nextCursor: string | null;
+};
+/**
+ * Lookup by id. When scope is provided, cross-scope ids fail closed as NOT_FOUND
+ * without revealing that the foreign resource exists.
+ */
+declare function inspectUser(store: ManagementStore, id: string, scope?: ResourceScope): Principal;
+/** Fail-closed status validation shared by management + runtime lifecycle paths. */
+declare function parseUserStatusInput(status: unknown, stage?: string): "active" | "disabled" | undefined;
+/**
+ * Update name, email, and/or status for a principal (management snapshot).
+ * Soft-deleted users are fail-closed as NOT_FOUND. Status may be active|disabled
+ * (not deleted — use deleteUser). Cross-scope ids fail closed as NOT_FOUND.
+ * With DATABASE_URL prefer updateUserInAuth for runtime parity.
+ */
+declare function updateUser(store: ManagementStore, id: string, input: {
+  name?: string;
+  email?: string; /** Re-enable or set disabled without soft-delete. */
+  status?: "active" | "disabled" | string;
+  actor?: string;
+  source?: "cli" | "console" | "api" | "import" | "scim" | "system";
+  scope?: ResourceScope;
+}): Principal;
+/**
+ * Disable a principal (status=disabled). Soft-deleted and cross-scope ids fail
+ * closed as NOT_FOUND. Active management sessions for the user are revoked in
+ * the same audited mutation.
+ */
+declare function disableUser(store: ManagementStore, id: string, input?: {
+  actor?: string;
+  source?: "cli" | "console" | "api" | "import" | "scim" | "system";
+  scope?: ResourceScope;
+}): Principal;
+/**
+ * Soft-delete a principal (status=deleted). Removed from list/inspect thereafter.
+ * Cross-scope ids fail closed as NOT_FOUND. Active sessions are revoked atomically.
+ */
+declare function deleteUser(store: ManagementStore, id: string, input?: {
+  actor?: string;
+  source?: "cli" | "console" | "api" | "import" | "scim" | "system";
+  scope?: ResourceScope;
+}): Principal;
+declare function createOrganization(store: ManagementStore, input: {
+  name: string;
+  slug?: string;
+  id?: string;
+  projectId?: string;
+  environmentId?: string;
+  externalId?: string;
+  actor?: string;
+  source?: "cli" | "console" | "api" | "import";
+}): Organization;
+declare function listOrganizations(store: ManagementStore, filter?: {
+  environmentId?: string;
+  projectId?: string;
+  scope?: ResourceScope;
+}): Organization[];
+declare const ORGS_LIST_DEFAULT_PAGE_LIMIT = 100;
+declare const ORGS_LIST_MAX_PAGE_LIMIT = 1000;
+/**
+ * Cursor-paginated organizations listing (FOLLOW.md P2.3.1).
+ * Ordering: createdAt ascending, then id ascending (documented keyset).
+ */
+declare function listOrganizationsPage(store: ManagementStore, opts?: {
+  scope?: ResourceScope;
+  limit?: number; /** Opaque cursor from a previous page's nextCursor (fail-closed). */
+  cursor?: string;
+}): {
+  organizations: Organization[];
+  nextCursor: string | null;
+};
+declare function inspectOrganization(store: ManagementStore, id: string, scope?: ResourceScope): Organization;
+/**
+ * Update legitimate mutable organization fields: name and/or slug.
+ * Status is not mutable here — use archiveOrganization. Soft-archived and
+ * cross-scope ids fail closed as ORG_NOT_FOUND. Idempotent when values match.
+ * Audits only when at least one field actually changes.
+ */
+declare function updateOrganization(store: ManagementStore, id: string, input: {
+  name?: string;
+  slug?: string;
+  actor?: string;
+  source?: "cli" | "console" | "api" | "import" | "system";
+  scope?: ResourceScope;
+}): Organization;
+type ArchiveOrganizationResult = {
+  organization: Organization;
+  dryRun: boolean;
+  idempotent: boolean;
+  wouldChange: boolean;
+};
+/**
+ * Archive an organization (status=archived). Requires confirm=true for mutation
+ * (CLI --yes). Dry-run previews without audit. Idempotent re-archive succeeds
+ * without a second audit when already archived. Membership list/add/update/remove
+ * and org inspect remain fail-closed for archived orgs (recovery via audit + row).
+ */
+declare function archiveOrganization(store: ManagementStore, id: string, input?: {
+  dryRun?: boolean; /** Required for mutation. CLI maps --yes → confirm=true. */
+  confirm?: boolean;
+  actor?: string;
+  source?: "cli" | "console" | "api" | "import" | "system";
+  scope?: ResourceScope;
+}): ArchiveOrganizationResult;
+declare const USERS_EXPORT_DEFAULT_LIMIT = 100;
+declare const USERS_EXPORT_MAX_LIMIT = 1000;
+declare const USERS_EXPORT_FORMATS: readonly ["json", "jsonl"];
+type UsersExportFormat = (typeof USERS_EXPORT_FORMATS)[number];
+type UsersExportOptions = {
+  limit?: number; /** Filter by principal status (active|disabled). Deleted never exported. */
+  status?: "active" | "disabled" | string;
+  format?: UsersExportFormat | string; /** Absolute or relative path; when set, artifact is written atomically (CLI only) */
+  outputPath?: string;
+  force?: boolean;
+  scope?: ResourceScope;
+  actor?: string;
+  source?: "cli" | "console" | "api" | "system";
+  skipAudit?: boolean;
+};
+type UsersExportEnvelope = {
+  schemaVersion: 1;
+  kind: "users.export";
+  exportedAt: string;
+  format: UsersExportFormat;
+  scope: ResourceScope;
+  limit: number;
+  count: number;
+  truncated: boolean;
+  filters: {
+    status?: "active" | "disabled";
+  };
+  users: Principal[];
+  outputPath?: string;
+  correlationId: string;
+};
+declare function normalizeUsersExportLimit(limit: number | undefined): number;
+declare function normalizeUsersExportFormat(format: string | undefined): UsersExportFormat;
+declare function normalizeUsersExportStatus(status: string | undefined): "active" | "disabled" | undefined;
+/** Stable sort: email asc, then id asc. */
+declare function sortUsersDeterministic(users: Principal[]): Principal[];
+/** Public export view of a principal — no write-only secrets (none stored). */
+declare function sanitizePrincipalForExport(user: Principal): Principal;
+declare function selectUsersForExport(store: ManagementStore, filter: {
+  limit: number;
+  status?: "active" | "disabled";
+  scope: ResourceScope;
+}): {
+  users: Principal[];
+  truncated: boolean;
+};
+/**
+ * Export principals: scoped, bounded, redacted, deterministic.
+ * Optional file write is atomic and refuse-overwrite by default (CLI).
+ * Audit never persists local filesystem paths — only wroteFile boolean.
+ */
+declare function exportUsers(store: ManagementStore, opts?: UsersExportOptions): UsersExportEnvelope;
+declare function listEvents(store: ManagementStore, filter?: {
+  limit?: number;
+  organizationId?: string;
+  action?: string;
+  scope?: ResourceScope;
+}): AuditEvent[];
+declare const EVENTS_LIST_DEFAULT_PAGE_LIMIT = 50;
+declare const EVENTS_LIST_MAX_PAGE_LIMIT = 1000;
+/**
+ * Cursor-paginated audit events listing (FOLLOW.md P2.3.1).
+ * Ordering: createdAt descending, then id descending (newest first — matches
+ * the deterministic export order in events.ts). Keyset cursors survive the
+ * prepend-heavy events array where index cursors would duplicate rows.
+ */
+declare function listEventsPage(store: ManagementStore, filter?: {
+  limit?: number;
+  organizationId?: string;
+  action?: string;
+  scope?: ResourceScope; /** Opaque cursor from a previous page's nextCursor (fail-closed). */
+  cursor?: string;
+}): {
+  events: AuditEvent[];
+  nextCursor: string | null;
+};
+declare function createSession(store: ManagementStore, input: {
+  principalId: string;
+  environmentId: string;
+  scope?: ResourceScope;
+}): SessionRecord;
+declare function overviewStats(store: ManagementStore, scope?: ResourceScope): {
+  totalUsers: number;
+  activeUsers: number;
+  organizations: number;
+  activeSessions: number;
+  recentEvents: AuditEvent[];
+  releaseVersion: string;
+  schemaVersion: number;
+  resourceCounts: Record<string, number>;
+};
+//#endregion
+//#region src/services/export-artifact.d.ts
+type WriteExportArtifactCodes = {
+  /** Audit/export stage string (e.g. events.export) */stage?: string; /** Error code when destination exists and force is false */
+  existsCode?: string; /** Error code when write fails for other reasons */
+  writeFailedCode?: string;
+};
+/**
+ * Write export body atomically. Refuses to overwrite unless force.
+ * On failure leaves no partial final artifact at outputPath.
+ * Mode 0o600 — owner read/write only.
+ */
+declare function writeExportArtifact(outputPath: string, body: string, force: boolean, codes?: WriteExportArtifactCodes): string;
+//#endregion
+//#region src/services/events.d.ts
+declare const EVENTS_EXPORT_DEFAULT_LIMIT = 100;
+declare const EVENTS_EXPORT_MAX_LIMIT = 1000;
+declare const EVENTS_TAIL_DEFAULT_LIMIT = 20;
+declare const EVENTS_TAIL_MAX_LIMIT = 1000;
+declare const EVENTS_EXPORT_FORMATS: readonly ["json", "jsonl"];
+type EventsExportFormat = (typeof EVENTS_EXPORT_FORMATS)[number];
+type EventsTailFilter = {
+  organizationId?: string;
+  action?: string;
+  scope?: ResourceScope;
+};
+/**
+ * Tail cursor state is intentionally local to one CLI invocation. It records
+ * every event visible at startup so a later poll never backfills old history.
+ */
+type EventsTailCursor = {
+  readonly scope: ResourceScope;
+  readonly organizationId?: string;
+  readonly action?: string;
+  readonly seenIds: Set<string>;
+};
+/**
+ * Subsystems with a defined safe diagnostic re-record path.
+ * Only SCIM has a repository replay service today (no domain state mutation).
+ */
+declare const REPLAYABLE_TRACE_SUBSYSTEMS: readonly ["scim"];
+type ReplayableTraceSubsystem = (typeof REPLAYABLE_TRACE_SUBSYSTEMS)[number];
+type EventsExportOptions = {
+  limit?: number;
+  organizationId?: string;
+  action?: string;
+  /**
+   * Export only events created strictly BEFORE this ISO-8601 timestamp.
+   * Archival bound (see audit.ts header): schedule exports with --before so
+   * events are captured before the retention cap prunes them.
+   */
+  before?: string; /** json (envelope) or jsonl (one event object per line) */
+  format?: EventsExportFormat | string; /** Absolute or relative path; when set, artifact is written atomically */
+  outputPath?: string; /** Allow replacing an existing file at outputPath */
+  force?: boolean;
+  scope?: ResourceScope;
+  actor?: string;
+  source?: AuditEvent["source"]; /** When true, skip privileged-read audit (tests / nested callers) */
+  skipAudit?: boolean;
+};
+type EventsExportEnvelope = {
+  schemaVersion: 1;
+  kind: "events.export";
+  exportedAt: string;
+  format: EventsExportFormat;
+  scope: ResourceScope;
+  limit: number;
+  count: number;
+  truncated: boolean;
+  filters: {
+    organizationId?: string;
+    action?: string;
+    before?: string;
+  };
+  events: AuditEvent[];
+  outputPath?: string;
+  correlationId: string;
+};
+type EventInspectResult = {
+  event?: AuditEvent;
+  trace?: DiagnosticTrace;
+  scope: ResourceScope;
+  replayable: boolean;
+  replayBlocker?: string;
+};
+type ReplayDiagnosticOptions = {
+  /** Preview only — default safe path when confirm is not true */dryRun?: boolean;
+  /**
+   * Required for mutating apply. CLI maps --yes → confirm=true.
+   * When confirm is not true, the service always dry-runs.
+   */
+  confirm?: boolean;
+  scope?: ResourceScope;
+  actor?: string;
+  source?: AuditEvent["source"];
+};
+type ReplayDiagnosticResult = {
+  dryRun: boolean;
+  idempotent: boolean;
+  wouldChange: boolean;
+  replayable: true;
+  original: DiagnosticTrace;
+  trace: DiagnosticTrace;
+  scope: ResourceScope;
+  auditAction?: "events.replay" | "scim.replay";
+};
+declare function normalizeEventsExportLimit(limit: number | undefined): number;
+declare function normalizeEventsTailLimit(limit: number | undefined): number;
+/** Fail-closed --before parsing: ISO-8601, normalized for lexical compare. */
+declare function normalizeEventsExportBefore(before: string | undefined): string | undefined;
+declare function normalizeEventsExportFormat(format: string | undefined): EventsExportFormat;
+/** Stable sort: newest first, then id descending for total order. */
+declare function sortEventsDeterministic(events: AuditEvent[]): AuditEvent[];
+/** Defense-in-depth redaction of an already-stored audit event. */
+declare function sanitizeAuditEvent(event: AuditEvent): AuditEvent;
+declare function selectEventsForExport(store: ManagementStore, filter: {
+  limit: number;
+  organizationId?: string;
+  action?: string; /** Normalized ISO bound — only events with createdAt strictly before */
+  before?: string;
+  scope: ResourceScope;
+}): {
+  events: AuditEvent[];
+  truncated: boolean;
+};
+/**
+ * Select the newest N matching events, then emit that initial history oldest
+ * first. All currently visible ids become the cursor baseline; later polls
+ * therefore only emit events that appeared after tailing began.
+ */
+declare function beginEventsTail(store: ManagementStore, filter?: EventsTailFilter & {
+  limit?: number;
+}): {
+  cursor: EventsTailCursor;
+  events: AuditEvent[];
+};
+/**
+ * Return newly observed scoped events in chronological order. Callers refresh
+ * their store before every poll; this works for both shared Postgres and a
+ * JsonStore modified by another process.
+ */
+declare function pollEventsTail(store: ManagementStore, cursor: EventsTailCursor): AuditEvent[];
+/**
+ * Export audit events: scoped, bounded, redacted, deterministic.
+ * Optional file write is atomic and refuse-overwrite by default.
+ */
+declare function exportEvents(store: ManagementStore, opts?: EventsExportOptions): EventsExportEnvelope;
+declare function isReplayableTraceSubsystem(subsystem: DiagnosticTrace["subsystem"]): subsystem is ReplayableTraceSubsystem;
+/**
+ * Inspect an audit event and/or diagnostic trace by id / correlation id.
+ * Fail closed for wrong-scope resources (same as missing).
+ */
+declare function inspectEvent(store: ManagementStore, id: string, opts?: {
+  scope?: ResourceScope;
+}): EventInspectResult;
+/**
+ * Replay a diagnostic trace via the shared SCIM replay service.
+ *
+ * - Defaults to dry-run when dryRun is true or confirm is not set.
+ * - Mutating apply requires confirm=true (CLI --yes) and only works for SCIM.
+ * - Idempotent: a prior scim.replay/events.replay of the same original returns
+ *   the existing artifact without writing another.
+ * - Never re-executes directory mutations or arbitrary audit actions.
+ */
+declare function replayDiagnosticTrace(store: ManagementStore, id: string, opts?: ReplayDiagnosticOptions): ReplayDiagnosticResult;
+//#endregion
+//#region src/services/sessions.d.ts
+/** Safe operator-facing session view — never includes token material. */
+type SessionView = {
+  id: string;
+  principalId: string;
+  projectId: string;
+  environmentId: string;
+  status: "active" | "revoked";
+  createdAt: string;
+  expiresAt?: string;
+  revokedAt?: string;
+  ipAddress?: string;
+  userAgent?: string;
+};
+type SessionSource = "cli" | "console" | "api" | "system";
+type RevokeSessionResult = {
+  session: SessionView; /** True when session was already revoked / absent under authorized contract */
+  idempotent: boolean;
+};
+declare function normalizeSessionLimit(limit: number | undefined): number;
+/**
+ * Strip any credential-like fields from a session-shaped object before return.
+ * Defense in depth: list/revoke must never surface raw tokens.
+ */
+declare function sanitizeSessionView(input: Record<string, unknown>): SessionView;
+declare function toSessionView(session: SessionRecord, projectId: string, extra?: Partial<SessionView>): SessionView;
+/**
+ * List management-snapshot sessions under principal-derived scope.
+ * Defaults to active only. Does not audit (list is not privileged-write).
+ */
+declare function listSessions(store: ManagementStore, opts?: {
+  scope?: ResourceScope; /** When true, include revoked tombstones */
+  includeRevoked?: boolean;
+  limit?: number;
+}): SessionView[];
+/**
+ * Cursor-paginated management-snapshot sessions (FOLLOW.md P2.3.1).
+ * Ordering: createdAt descending, then id descending (newest first; the id
+ * tiebreak makes the keyset a strict total order — see pagination.ts).
+ * Postgres runtime sessions paginate via listSessionsPageInAuth (auth-bridge).
+ */
+declare function listSessionsPage(store: ManagementStore, opts?: {
+  scope?: ResourceScope; /** When true, include revoked tombstones */
+  includeRevoked?: boolean;
+  limit?: number; /** Opaque cursor from a previous page's nextCursor (fail-closed). */
+  cursor?: string;
+}): {
+  sessions: SessionView[];
+  nextCursor: string | null;
+};
+/** Load one safe session view under scope without changing state. */
+declare function inspectSession(store: ManagementStore, id: string, opts?: {
+  scope?: ResourceScope;
+}): SessionView;
+/**
+ * Revoke a management-snapshot session by stable id.
+ * Idempotent: already-revoked under scope returns success with idempotent=true.
+ * Missing or cross-scope fails closed as SESSION_NOT_FOUND.
+ * Always writes an audit event (including idempotent re-revoke).
+ */
+declare function revokeSession(store: ManagementStore, id: string, input?: {
+  actor?: string;
+  source?: SessionSource;
+  scope?: ResourceScope;
+}): RevokeSessionResult;
+/** Test/helper: ensure principal exists in scope (re-export pattern). */
+declare function assertSessionPrincipalInScope(store: ManagementStore, principalId: string, scope?: ResourceScope): void;
+//#endregion
+//#region src/services/api-keys.d.ts
+type ApiKeyView = Omit<ApiKey, "digest">;
+type CreatedApiKey = {
+  apiKey: ApiKeyView;
+  secret: string;
+};
+/** Strict normalized scope validation: lowercase, no empty/malformed/duplicates. */
+declare function normalizeAndValidateApiKeyScopes(input: unknown, stage: string): string[];
+declare function validateApiKeyName(value: unknown, stage: string): string;
+declare function listApiKeys(store: ManagementStore, input?: {
+  scope?: ResourceScope;
+  includeRevoked?: boolean;
+}): ApiKeyView[];
+declare function inspectApiKey(store: ManagementStore, id: string, input?: {
+  scope?: ResourceScope;
+}): ApiKeyView;
+declare function createApiKey(store: ManagementStore, input: {
+  name: unknown;
+  scopes?: unknown;
+  projectId?: string;
+  environmentId?: string;
+  scope?: ResourceScope;
+  actor?: string;
+  source?: "cli" | "console" | "api";
+}): Promise<CreatedApiKey>;
+declare function rotateApiKey(store: ManagementStore, id: string, input?: {
+  scope?: ResourceScope;
+  actor?: string;
+  source?: "cli" | "console" | "api";
+}): Promise<CreatedApiKey & {
+  revokedKey: ApiKeyView;
+}>;
+declare function revokeApiKey(store: ManagementStore, id: string, input?: {
+  scope?: ResourceScope;
+  actor?: string;
+  source?: "cli" | "console" | "api";
+}): Promise<{
+  apiKey: ApiKeyView;
+  idempotent: boolean;
+}>;
+//#endregion
+//#region src/services/roles.d.ts
+/** Reserved built-in role slugs — cannot be created or mutated as custom roles */
+declare const BUILT_IN_ROLE_SLUGS: readonly ["owner", "admin", "member"];
+type BuiltInRoleSlug = (typeof BUILT_IN_ROLE_SLUGS)[number];
+declare function isBuiltInRoleSlug(slug: string): slug is BuiltInRoleSlug;
+declare function builtInRoleId(slug: BuiltInRoleSlug): string;
+type AssignableRole = {
+  slug: string;
+  kind: "built_in" | "custom";
+  roleId: string;
+};
+/**
+ * Resolve a role slug for membership assignment within principal-derived scope.
+ * Built-in owner/admin/member always accepted. Custom roles must be active and
+ * in the same project/environment; organization-bound roles must match the org.
+ * Fail closed with stable structured errors for missing/foreign/disabled/archived.
+ */
+declare function resolveAssignableRole(store: ManagementStore, roleInput: unknown, opts: {
+  scope: ResourceScope;
+  organizationId: string;
+  stage: string;
+}): AssignableRole;
+/**
+ * Normalize and validate permission tokens.
+ * - trim + lowercase
+ * - reject empty / malformed / duplicates
+ * - return stably sorted unique list
+ */
+declare function normalizeAndValidatePermissions(input: unknown, stage: string): string[];
+declare function validateRoleName(name: unknown, stage: string): string;
+declare function validateRoleSlug(slug: unknown, stage: string): string;
+/**
+ * Pure validation of a role draft (name/slug/permissions).
+ * Requires scope resolution for API consistency even though nothing is persisted.
+ */
+declare function validateRole(store: ManagementStore, input: {
+  name?: unknown;
+  slug?: unknown;
+  permissions?: unknown;
+  scope?: ResourceScope;
+  projectId?: string;
+  environmentId?: string;
+}): {
+  ok: true;
+  name?: string;
+  slug?: string;
+  permissions?: string[];
+  scope: ResourceScope;
+};
+declare function listRoles(store: ManagementStore, filter?: {
+  scope?: ResourceScope;
+}): CustomRole[];
+declare function inspectRole(store: ManagementStore, id: string, scope?: ResourceScope): CustomRole;
+declare function createRole(store: ManagementStore, input: {
+  name: string;
+  slug?: string;
+  description?: string;
+  permissions: string[];
+  projectId?: string;
+  environmentId?: string;
+  actor?: string;
+  source?: "cli" | "console" | "api";
+  scope?: ResourceScope;
+}): Promise<CustomRole>;
+declare function updateRole(store: ManagementStore, id: string, input: {
+  name?: string;
+  description?: string | null;
+  permissions?: string[];
+  actor?: string;
+  source?: "cli" | "console" | "api";
+  scope?: ResourceScope;
+}): Promise<CustomRole>;
+//#endregion
+//#region src/services/members-import.d.ts
+type MemberImportFormat = "json" | "csv";
+type MemberImportPlanRow = {
+  row: number;
+  principalId: string;
+  role: string;
+  idempotent: boolean;
+};
+type MemberImportPlan = {
+  organizationId: string;
+  format: MemberImportFormat;
+  rows: MemberImportPlanRow[];
+  summary: {
+    total: number;
+    wouldAdd: number;
+    idempotent: number;
+  };
+};
+type MemberImportRowResult = {
+  row: number;
+  principalId: string;
+  status: "success" | "idempotent" | "failure";
+  error?: {
+    code: string;
+    stage: string;
+    retryable: boolean;
+  };
+};
+type MemberImportResult = MemberImportPlan["summary"] & {
+  completed: true;
+  partial: boolean;
+  results: MemberImportRowResult[];
+  success: number;
+  failure: number;
+};
+declare function planMemberImport(store: ManagementStore, input: {
+  organizationId: string;
+  content: string;
+  format: MemberImportFormat;
+}): MemberImportPlan;
+/** Applies a fully validated plan in deterministic file order. Each callback is durable before the next row. */
+declare function executeMemberImportPlan(plan: MemberImportPlan, apply: (row: MemberImportPlanRow) => Promise<Membership>): Promise<MemberImportResult>;
+//#endregion
+//#region src/services/identity.d.ts
+type RuntimeUserIdentity = {
+  /** Canonical Clearance / runtime user id — becomes management principal id */id: string;
+  email: string;
+  name: string;
+  createdAt?: string | Date;
+  updatedAt?: string | Date;
+};
+type RuntimeOrganizationIdentity = {
+  id: string;
+  name: string;
+  slug: string;
+  createdAt?: string | Date;
+  /**
+   * Canonical Clearance owner membership id. When present, management
+   * membership for the owner uses this exact stable id (create or reconcile).
+   */
+  ownerMembershipId?: string;
+};
+/**
+ * Persist a runtime user into the management store with the identical stable id.
+ * Safe to call repeatedly (idempotent by id and by email-within-scope).
+ *
+ * For Postgres, call syncRuntimeUserToManagementDurable (or await store.ready())
+ * so durability and constraint failures surface.
+ */
+declare function syncRuntimeUserToManagement(store: ManagementStore, runtimeUser: RuntimeUserIdentity, opts?: {
+  projectId?: string;
+  environmentId?: string;
+  actor?: string;
+  source?: "cli" | "console" | "api" | "system" | "scim";
+}): Principal;
+/**
+ * Async variant that awaits durable commit (required for Postgres backend).
+ * Does not swallow failures — rethrows after ready().
+ */
+declare function syncRuntimeUserToManagementDurable(store: ManagementStore, runtimeUser: RuntimeUserIdentity, opts?: {
+  projectId?: string;
+  environmentId?: string;
+  actor?: string;
+  source?: "cli" | "console" | "api" | "system" | "scim";
+}): Promise<Principal>;
+/**
+ * Mirror a runtime organization and its owner membership into the canonical
+ * scoped management view while preserving the runtime organization id.
+ * When ownerMembershipId is provided, management uses that exact stable
+ * membership id (create or reconcile). Organization, membership, and audit
+ * records commit in one store mutation.
+ */
+declare function syncRuntimeOrganizationToManagementDurable(store: ManagementStore, runtimeOrganization: RuntimeOrganizationIdentity, ownerPrincipalId: string, opts?: {
+  projectId?: string;
+  environmentId?: string;
+  actor?: string;
+  role?: string;
+}): Promise<Organization>;
+//#endregion
+//#region src/services/doctor.d.ts
+declare function runDoctor(store: ManagementStore, opts?: {
+  dataPath?: string;
+  secrets?: Record<string, string | undefined>;
+}): Promise<{
+  checks: DoctorCheck[];
+  ok: boolean;
+  releaseVersion: string;
+}>;
+//#endregion
+//#region src/services/sso.d.ts
+type SsoActorSource = "cli" | "console" | "api" | "system";
+interface SsoMutationOpts {
+  actor?: string;
+  source?: SsoActorSource;
+  scope?: ResourceScope;
+}
+/**
+ * Resolve an SSO connection under principal-derived org scope.
+ * Missing and cross-scope ids fail closed as SSO_NOT_FOUND.
+ */
+declare function resolveSsoConnection(store: ManagementStore, id: string, opts?: {
+  scope?: ResourceScope;
+  stage?: string;
+}): IdentityConnection;
+/** Public inspect — never returns encrypted secret material. */
+declare function inspectSsoConnection(store: ManagementStore, id: string, opts?: {
+  scope?: ResourceScope;
+}): IdentityConnection;
+interface SsoCreateInput {
+  organizationId: string;
+  protocol: "saml" | "oidc";
+  provider: string;
+  issuer?: string;
+  audience?: string;
+  metadataUrl?: string;
+  clientId?: string;
+  clientSecret?: string;
+  samlEntryPoint?: string;
+  samlCertificate?: string;
+  domains?: string[];
+  actor?: string;
+}
+declare function createSsoConnection(store: ManagementStore, input: SsoCreateInput): IdentityConnection;
+/**
+ * Configure an SSO connection under principal-derived scope (FOLLOW.md P2.3.5).
+ * Missing and cross-scope ids fail closed as SSO_NOT_FOUND with no write —
+ * the same scope contract as rotateSsoCredential / disableSsoConnection.
+ * Validation + write + audit run in ONE store.mutate against the draft
+ * (core.ts atomic mutation pattern), so Postgres FOR UPDATE commits the
+ * configure and its audit event together or not at all.
+ */
+declare function configureSsoConnection(store: ManagementStore, id: string, patch: Partial<Pick<IdentityConnection, "issuer" | "audience" | "metadataUrl" | "clientId" | "domains" | "attributeMapping" | "status">> & {
+  clientSecret?: string;
+}, opts?: SsoMutationOpts): IdentityConnection;
+declare function listSsoConnections(store: ManagementStore, organizationId?: string): IdentityConnection[];
+/**
+ * Rotate stored SSO client secret envelope under the current credential key.
+ * Plaintext is preserved; only AEAD key envelope / fingerprint metadata change.
+ * Never returns encrypted material — fingerprints only.
+ */
+declare function rotateSsoCredential(store: ManagementStore, id: string, opts?: SsoMutationOpts): IdentityConnection;
+/**
+ * Disable an SSO connection (status=disabled). Idempotent when already disabled.
+ * Management-only path; prefer disableSsoConnectionReal when DATABASE_URL is set
+ * so runtime ssoProvider rows stay coherent.
+ */
+declare function disableSsoConnection(store: ManagementStore, id: string, opts?: SsoMutationOpts): {
+  connection: IdentityConnection;
+  idempotent: boolean;
+};
+/**
+ * Disable SSO connection and remove the matching runtime ssoProvider row.
+ * Uses mutateCoordinated when available (Postgres) so management + runtime
+ * commit together; otherwise best-effort runtime delete then management disable.
+ */
+declare function disableSsoConnectionReal(store: ManagementStore, id: string, opts?: SsoMutationOpts): Promise<{
+  connection: IdentityConnection;
+  idempotent: boolean;
+  runtimeRemoved: boolean;
+}>;
+interface SsoTestOptions {
+  /**
+   * Lab/fixture path — always simulation mode (not live IdP conformance).
+   * Fail-closed: unknown fixtures throw rather than pass.
+   */
+  fixture?: "ok" | "wrong-issuer" | "wrong-audience" | "malformed" | "expired" | "clock-skew" | "replay";
+  assertionIssuer?: string;
+  assertionAudience?: string;
+}
+/** All fixture-driven SSO tests are simulation (not live conformance). */
+declare const SSO_FIXTURE_MODE: "simulation";
+declare function testSsoConnection(store: ManagementStore, id: string, opts?: SsoTestOptions): {
+  pass: boolean;
+  trace: DiagnosticTrace;
+  connection: IdentityConnection;
+  mode: "simulation";
+};
+//#endregion
+//#region src/services/scim.d.ts
+type ScimActorSource = "cli" | "console" | "api" | "system";
+interface ScimMutationOpts {
+  actor?: string;
+  source?: ScimActorSource;
+  scope?: ResourceScope;
+}
+/**
+ * Resolve a SCIM directory connection under principal-derived org scope.
+ * Missing and cross-scope ids fail closed as SCIM_NOT_FOUND.
+ */
+declare function resolveScimConnection(store: ManagementStore, id: string, opts?: {
+  scope?: ResourceScope;
+  stage?: string;
+}): DirectoryConnection;
+/** Public inspect — never returns encrypted bearer material. */
+declare function inspectScimConnection(store: ManagementStore, id: string, opts?: {
+  scope?: ResourceScope;
+}): DirectoryConnection;
+declare function createScimConnection(store: ManagementStore, input: {
+  organizationId: string;
+  provider: string;
+  endpoint?: string;
+  bearerToken?: string;
+  deprovisioningPolicy?: DirectoryConnection["deprovisioningPolicy"];
+  actor?: string;
+}): DirectoryConnection;
+declare function listScimConnections(store: ManagementStore, organizationId?: string): DirectoryConnection[];
+/**
+ * Rotate stored SCIM bearer envelope under the current credential key.
+ * Plaintext token is preserved; only AEAD envelope / fingerprint metadata change.
+ * Never returns encrypted material — fingerprints only.
+ */
+declare function rotateScimCredential(store: ManagementStore, id: string, opts?: ScimMutationOpts): DirectoryConnection;
+/**
+ * Disable a SCIM directory connection (status=disabled). Idempotent when already disabled.
+ * Management-only path; prefer disableScimConnectionReal when DATABASE_URL is set
+ * so runtime scimProvider rows stay coherent.
+ */
+declare function disableScimConnection(store: ManagementStore, id: string, opts?: ScimMutationOpts): {
+  connection: DirectoryConnection;
+  idempotent: boolean;
+};
+/**
+ * Disable SCIM connection and remove the matching runtime scimProvider row.
+ * Coordinated when Postgres mutateCoordinated is available.
+ */
+declare function disableScimConnectionReal(store: ManagementStore, id: string, opts?: ScimMutationOpts): Promise<{
+  connection: DirectoryConnection;
+  idempotent: boolean;
+  runtimeRemoved: boolean;
+}>;
+interface ScimUserPayload {
+  userName: string;
+  displayName?: string;
+  active?: boolean;
+  externalId?: string;
+}
+/** Fixture-driven SCIM apply path is simulation (not live directory conformance). */
+declare const SCIM_FIXTURE_MODE: "simulation";
+/** Local HTTP protocol probe evidence label — not external provider certification. */
+declare const SCIM_LOCAL_PROTOCOL_EVIDENCE: "local protocol verification (not external IdP/directory certification)";
+/**
+ * Perform an actual SCIM HTTP connection check against the configured endpoint.
+ * Network / auth / malformed body / non-success status all fail.
+ */
+declare function checkScimConnection(store: ManagementStore, id: string, opts?: {
+  /** Override token (tests); otherwise decrypt stored envelope */bearerToken?: string;
+  path?: string;
+  fetchImpl?: typeof fetch;
+}): Promise<{
+  pass: boolean;
+  trace: DiagnosticTrace;
+  connection: DirectoryConnection;
+  mode: "simulation";
+  evidence: typeof SCIM_LOCAL_PROTOCOL_EVIDENCE;
+  externalProviderCertified: false;
+}>;
+declare function testScimConnection(store: ManagementStore, id: string, opts?: {
+  dryRun?: boolean;
+  users?: ScimUserPayload[];
+  fixture?: "ok" | "malformed" | "unauthorized";
+}): {
+  pass: boolean;
+  trace: DiagnosticTrace;
+  proposed: Array<{
+    action: string;
+    email: string;
+  }>;
+  connection: DirectoryConnection;
+  mode: "simulation";
+};
+/**
+ * Validate that a SCIM diagnostic trace is visible under principal scope.
+ * Used by dry-run and by replay before mutation.
+ */
+declare function inspectScimTrace(store: ManagementStore, traceId: string, opts?: {
+  scope?: ResourceScope;
+}): DiagnosticTrace;
+/**
+ * Replay a SCIM diagnostic trace under principal-derived scope.
+ * Writes a new trace row + audit; never mutates directory connections or tokens.
+ */
+declare function replayScimTrace(store: ManagementStore, traceId: string, opts?: ScimMutationOpts): DiagnosticTrace;
+//#endregion
+//#region src/services/scim-probe.d.ts
+type ScimProbeOutcome = {
+  ok: true;
+  status: number;
+  path: string;
+  bodySnippet: string;
+} | {
+  ok: false;
+  reason: "network" | "authentication" | "malformed_body" | "non_success";
+  status?: number;
+  message: string;
+  path?: string;
+};
+type ScimProbeOptions = {
+  endpoint: string;
+  bearerToken?: string; /** Relative path under endpoint (default ServiceProviderConfig) */
+  path?: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+};
+/**
+ * Issue a real SCIM GET against the connection endpoint.
+ * Uses application/scim+json Accept and optional Bearer token.
+ */
+declare function probeScimEndpoint(opts: ScimProbeOptions): Promise<ScimProbeOutcome>;
+declare function probeOutcomeToError(outcome: Extract<ScimProbeOutcome, {
+  ok: false;
+}>): ClearanceError;
+/**
+ * Deterministic local SCIM HTTP fixture for tests.
+ * Modes: ok | unauthorized | malformed | non_success
+ */
+declare function createLocalScimFixtureServer(mode?: "ok" | "unauthorized" | "malformed" | "non_success", expectedToken?: string): {
+  server: ReturnType<typeof createServer>;
+  listen: () => Promise<{
+    baseUrl: string;
+    port: number;
+  }>;
+  close: () => Promise<void>;
+  requests: Array<{
+    method?: string;
+    url?: string;
+    authorization?: string;
+  }>;
+};
+//#endregion
+//#region src/services/sso-real.d.ts
+type SsoTestFixture = "ok" | "okta" | "entra" | "wrong-issuer" | "wrong-audience" | "malformed" | "expired" | "clock-skew" | "local-oidc";
+/** Fixture/matrix paths use simulation mode — not live IdP conformance. */
+declare const SSO_REAL_FIXTURE_MODE: "simulation";
+/** Matrix fixtures (okta/entra JSON) are never tenant certification. */
+declare const SSO_MATRIX_NOT_CERTIFIED: false;
+declare function validateSamlProviderConfig(input: {
+  entryPoint?: string;
+  certificate?: string;
+}): {
+  entryPoint: string;
+  certificate: string;
+  fingerprint: string;
+};
+/**
+ * Create SSO connection from a matrix fixture file (Okta/Entra) or explicit opts.
+ * Persists into real ssoProvider table and validates discovery URL with upstream util.
+ *
+ * When `setupAttemptId` is set (customer setup reserve path), connection and
+ * runtime provider ids are deterministic for crash-safe retry reconcile.
+ * Without it, ids remain generated (CLI/operator path).
+ */
+declare function createSsoConnectionReal(store: ManagementStore, input: {
+  organizationId: string;
+  protocol?: "saml" | "oidc";
+  provider?: string;
+  issuer?: string;
+  audience?: string;
+  domain?: string;
+  clientId?: string;
+  clientSecret?: string;
+  samlEntryPoint?: string;
+  samlCertificate?: string; /** Load fixtures/sso/{matrix}-oidc.json — okta | entra */
+  matrix?: "okta" | "entra";
+  fixturePath?: string;
+  actor?: string;
+  /**
+   * Setup reservation/attempt id. When set, derives stable runtime +
+   * management ids and reuses them across retries after lease expiry.
+   */
+  setupAttemptId?: string;
+}): Promise<IdentityConnection>;
+/**
+ * Test SSO using real @clearance/sso validators.
+ * Fixture names map to fixtures/sso/adversarial-cases.json or matrix discovery files.
+ */
+declare function testSsoConnectionReal(store: ManagementStore, id: string, opts?: {
+  fixture?: SsoTestFixture;
+}): {
+  pass: boolean;
+  trace: DiagnosticTrace;
+  connection: IdentityConnection;
+  mode: "simulation";
+  certifiedExternalTenant?: false;
+  evidence?: string;
+} | Promise<{
+  pass: boolean;
+  trace: DiagnosticTrace;
+  connection: IdentityConnection;
+  mode: "simulation";
+  certifiedExternalTenant?: false;
+  evidence?: string;
+  authorizationUrl?: string;
+}>;
+/** Run Okta + Entra positive matrix against a connection's registered issuer. */
+declare function runSsoMatrix(store: ManagementStore, connectionId: string): {
+  okta: boolean;
+  entra: boolean;
+};
+//#endregion
+//#region src/services/sso-local.d.ts
+declare const SSO_LOCAL_PROTOCOL_MODE: "simulation";
+declare const SSO_LOCAL_EVIDENCE_LABEL: "local protocol verification (not Okta/Entra tenant certification)";
+declare function generatePkcePair(): {
+  codeVerifier: string;
+  codeChallenge: string;
+  codeChallengeMethod: "S256";
+};
+declare function buildAuthorizationUrl(input: {
+  authorizationEndpoint: string;
+  clientId: string;
+  redirectUri: string;
+  state: string;
+  nonce: string;
+  codeChallenge: string;
+  codeChallengeMethod?: string;
+  scope?: string;
+}): string;
+type LocalOidcSession = {
+  state: string;
+  nonce: string;
+  codeVerifier: string;
+  codeChallenge: string;
+  clientId: string;
+  redirectUri: string;
+  issuedCode?: string;
+};
+/**
+ * Deterministic local OIDC issuer fixture (discovery + authorize + token).
+ * Validates state echo, PKCE S256, and returns id_token carrying nonce.
+ */
+declare function createLocalOidcIssuerFixture(opts?: {
+  clientId?: string;
+  clientSecret?: string;
+}): {
+  listen: () => Promise<{
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    jwksUri: string;
+    discovery: Record<string, unknown>;
+  }>;
+  close: () => Promise<void>;
+  sessions: Map<string, LocalOidcSession>;
+  registerSession: (session: LocalOidcSession) => void;
+};
+declare function decodeJwtPayload(idToken: string): Record<string, unknown>;
+/**
+ * Exercise full local OIDC authorize→callback→token path with state/nonce/PKCE.
+ * Labels evidence as local protocol verification; never Okta/Entra certification.
+ */
+declare function verifySsoOidcLocalProtocol(store: ManagementStore, connectionId: string, opts?: {
+  issuer?: {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    issuer: string;
+  };
+  clientId?: string;
+  redirectUri?: string;
+  fetchImpl?: typeof fetch;
+}): Promise<{
+  pass: boolean;
+  trace: DiagnosticTrace;
+  connection: IdentityConnection;
+  mode: "simulation";
+  evidence: typeof SSO_LOCAL_EVIDENCE_LABEL;
+  authorizationUrl: string;
+  certifiedExternalTenant: false;
+}>;
+//#endregion
+//#region src/services/scim-real.d.ts
+declare const SCIM_REAL_FIXTURE_MODE: "simulation";
+/**
+ * Create SCIM connection in runtime scimProvider + management store.
+ *
+ * When `setupAttemptId` is set (customer setup reserve path), connection and
+ * runtime provider ids are deterministic for crash-safe retry reconcile.
+ * SCIM bearer material stays encrypted at rest; plaintext is returned only as
+ * `bearerTokenOnce` on the successful create/recovery response (not re-fetchable).
+ */
+declare function createScimConnectionReal(store: ManagementStore, input: {
+  organizationId: string;
+  provider: string;
+  actor?: string;
+  /**
+   * External SCIM base URL. Defaults to the local setup endpoint;
+   * a real tenant URL is required for live conformance probes.
+   */
+  endpoint?: string;
+  /**
+   * Setup reservation/attempt id. When set, derives stable runtime +
+   * management ids and reuses them across retries after lease expiry.
+   */
+  setupAttemptId?: string;
+}): Promise<DirectoryConnection & {
+  bearerTokenOnce?: string;
+}>;
+/**
+ * Connection check against configured endpoint via real HTTP.
+ * When endpoint is absolute, uses checkScimConnection.
+ * Relative plugin paths are exercised via auth.handler ServiceProviderConfig GET.
+ */
+declare function testScimConnectionReal(store: ManagementStore, id: string, opts?: {
+  dryRun?: boolean;
+  fixture?: "ok" | "malformed" | "unauthorized";
+  users?: Array<{
+    userName: string;
+    displayName?: string;
+    active?: boolean;
+  }>; /** Absolute URL override for local fixture protocol verification */
+  endpointOverride?: string;
+  bearerToken?: string;
+  fetchImpl?: typeof fetch;
+}): Promise<{
+  pass: boolean;
+  trace: DiagnosticTrace;
+  proposed: Array<{
+    action: string;
+    email: string;
+  }>;
+  connection: DirectoryConnection;
+  mode: "simulation";
+  evidence?: string;
+  externalProviderCertified: false;
+}>;
+//#endregion
+//#region src/services/live-conformance.d.ts
+declare const LIVE_CONFORMANCE_MODE: "live";
+declare const LIVE_EVIDENCE_LABEL = "live read-only conformance probe against the configured external endpoint (not full sign-in certification)";
+declare function assertLiveEndpoint(rawUrl: string | undefined, subsystem: "sso" | "scim", stage: string): URL;
+interface LiveProbeResult<C> {
+  pass: boolean;
+  trace: DiagnosticTrace;
+  connection: C;
+  mode: typeof LIVE_CONFORMANCE_MODE;
+  evidence: string;
+  endpoint: string;
+}
+interface LiveProbeOptions {
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+/**
+ * Live OIDC conformance: fetch and validate the real discovery document and
+ * JWKS from the configured issuer. SAML connections refuse — live SAML
+ * metadata exchange needs a browser actor (rendered E2E), and pretending
+ * otherwise is exactly what this codebase does not do.
+ */
+declare function testSsoConnectionLive(store: ManagementStore, id: string, opts?: LiveProbeOptions): Promise<LiveProbeResult<IdentityConnection>>;
+/**
+ * Live SCIM conformance: real read-only GETs (ServiceProviderConfig, then a
+ * one-item Users page) against the configured endpoint with the stored
+ * bearer credential. Never mutates the tenant.
+ */
+declare function testScimConnectionLive(store: ManagementStore, id: string, opts?: LiveProbeOptions): Promise<LiveProbeResult<DirectoryConnection>>;
+//#endregion
+//#region src/services/setup-links.d.ts
+type SetupKind = "sso" | "scim";
+/** Bounded lease so a crashed holder does not permanently burn the capability. */
+declare const SETUP_RESERVATION_TTL_MS = 120000;
+/**
+ * Stable reservation / setup-attempt id derived from the capability digest.
+ * Same capability always re-leases the same attempt id after expiry so runtime
+ * and management rows can be reconciled without exposing the raw token.
+ */
+declare function deriveSetupReservationId(capabilityDigest: string): string;
+/**
+ * Deterministic runtime PK + unique providerId for a setup attempt.
+ * Used only when completing a reserved capability; normal CLI/operator creates
+ * keep generated ids. Material is a hash of kind+attempt — never the raw token.
+ */
+declare function deriveSetupConnectionIds(kind: SetupKind, setupAttemptId: string): {
+  connectionId: string;
+  providerId: string;
+};
+declare function createSetupLink(store: ManagementStore, input: {
+  organizationId: string;
+  kind: SetupKind;
+  ttlMinutes?: number;
+  actor?: string; /** Absolute console base; defaults to CLEARANCE_CONSOLE_URL */
+  baseUrl?: string;
+}): {
+  url: string;
+  expiresAt: string; /** Raw capability — return once; never persisted */
+  token: string;
+  tokenFingerprint: string;
+  capabilityId: string;
+};
+type RedeemSetupLinkInput = {
+  token: string;
+  kind: SetupKind; /** When set, must match capability */
+  organizationId?: string;
+  projectId?: string;
+  environmentId?: string;
+  actor?: string;
+};
+/**
+ * Atomically consume a setup capability (single durable mutation).
+ * Prefer reserve → provision → commit for flows with external side effects.
+ */
+declare function redeemSetupLink(store: ManagementStore, input: RedeemSetupLinkInput): Promise<SetupCapability>;
+type ReserveSetupLinkResult = {
+  capability: SetupCapability;
+  reservationId: string;
+};
+/**
+ * Atomically lease a setup capability for in-flight provisioning.
+ * Does not consume the capability; commit does. Concurrent reserves yield
+ * one winner and SETUP_LINK_IN_PROGRESS / REPLAY for losers.
+ */
+declare function reserveSetupLink(store: ManagementStore, input: RedeemSetupLinkInput & {
+  reservationTtlMs?: number;
+}): Promise<ReserveSetupLinkResult>;
+type CommitSetupLinkInput = RedeemSetupLinkInput & {
+  reservationId: string;
+};
+/**
+ * Atomically consume a previously reserved capability. Replay after commit fails.
+ * Never reopens a redeemed capability.
+ */
+declare function commitSetupLink(store: ManagementStore, input: CommitSetupLinkInput): Promise<SetupCapability>;
+type ReleaseSetupLinkInput = {
+  token: string;
+  kind: SetupKind;
+  reservationId: string;
+  actor?: string;
+};
+/**
+ * Drop an in-progress reservation after failed provisioning.
+ * Never un-consumes a committed (redeemed) capability.
+ */
+declare function releaseSetupLink(store: ManagementStore, input: ReleaseSetupLinkInput): Promise<SetupCapability | null>;
+declare function revokeSetupLink(store: ManagementStore, input: {
+  capabilityId?: string;
+  token?: string;
+  actor?: string;
+}): SetupCapability;
+declare function listSetupLinks(store: ManagementStore, organizationId?: string): Omit<SetupCapability, "digest">[];
+//#endregion
+//#region src/services/readiness.d.ts
+/**
+ * Enterprise readiness from control-plane state.
+ * Fixture/synthetic SSO+SCIM tests are labeled simulation and never set liveCertified.
+ */
+declare function runReadinessCheck(store: ManagementStore, organizationId: string): ReadinessReport;
+declare function getLatestReadiness(store: ManagementStore, organizationId: string): ReadinessReport;
+//#endregion
+//#region src/services/migration.d.ts
+/** Deliberately small, portable Clearance export contract accepted by Clearance. */
+interface LegacyExportFixture {
+  source: "legacy";
+  users: Array<{
+    id: string;
+    email: string;
+    name: string;
+  }>;
+  organizations: Array<{
+    id: string;
+    name: string;
+    slug?: string;
+  }>;
+  members: Array<{
+    userId: string;
+    organizationId: string;
+    role?: string;
+  }>;
+}
+type MigrationPreview = {
+  source: "legacy";
+  fixtureChecksum: string;
+  counts: {
+    users: number;
+    organizations: number;
+    members: number;
+  };
+  wouldCreate: {
+    users: number;
+    organizations: number;
+    members: number;
+  };
+  idempotent: {
+    users: number;
+    organizations: number;
+    members: number;
+  };
+};
+/** Reads and fully validates the one Legacy fixture shape supported by this lane. */
+declare function loadLegacyFixture(path: string): LegacyExportFixture;
+/** Validate conflicts and calculate a non-mutating Clearance import preview. */
+declare function previewMigration(store: ManagementStore, fixture: LegacyExportFixture): MigrationPreview;
+declare function planMigration(store: ManagementStore, fixture: LegacyExportFixture): MigrationPlan;
+declare function assertMigrationRunnable(plan: MigrationPlan, stage: string): void;
+declare function runMigration(store: ManagementStore, planId: string, fixture: LegacyExportFixture, opts?: {
+  dryRun?: boolean;
+}): MigrationPlan;
+declare function verifyMigration(store: ManagementStore, planId: string, fixture: LegacyExportFixture): {
+  plan: MigrationPlan;
+  reconciled: boolean;
+  actual: Record<string, number>;
+  expected: Record<string, number>;
+};
+declare function rollbackMigration(store: ManagementStore, planId: string, fixture: LegacyExportFixture): MigrationPlan;
+declare function migrationStatus(store: ManagementStore, planId: string): MigrationPlan;
+//#endregion
+//#region src/services/migration-postgres.d.ts
+declare function runMigrationDurable(store: ManagementStore, planId: string, fixture: LegacyExportFixture, opts?: {
+  dryRun?: boolean;
+}): Promise<MigrationPlan>;
+declare function verifyMigrationDurable(store: ManagementStore, planId: string, fixture: LegacyExportFixture): Promise<{
+  plan: MigrationPlan;
+  reconciled: boolean;
+  actual: Record<string, number>;
+  expected: Record<string, number>;
+} | {
+  plan: MigrationPlan;
+  reconciled: boolean;
+  actual: {
+    users: number;
+    organizations: number;
+    members: number;
+  };
+  expected: {
+    users: number;
+    organizations: number;
+    members: number;
+  };
+}>;
+declare function rollbackMigrationDurable(store: ManagementStore, planId: string, fixture: LegacyExportFixture): Promise<MigrationPlan>;
+//#endregion
+//#region src/services/runtime-schema.d.ts
+type RuntimeSchemaPlanResult = {
+  pendingTables: number;
+  pendingFields: number;
+  sql: string;
+};
+type RuntimeSchemaMetadata = Omit<RuntimeSchemaPlanResult, "sql">;
+/** Canonical Clearance migration plan used by status, generate, and migrate. */
+declare function planRuntimeSchema(stage?: string): Promise<RuntimeSchemaPlanResult>;
+declare function getRuntimeSchemaStatus(): Promise<{
+  configured: false;
+  state: "unconfigured";
+  pendingTables: 0;
+  pendingFields: 0;
+} | ({
+  configured: true;
+  state: "configured";
+} & RuntimeSchemaMetadata)>;
+declare function generateRuntimeSchema(input: {
+  outputPath: string;
+  force: boolean;
+  dryRun: boolean;
+}): Promise<{
+  outputId: string;
+  pendingTables: number;
+  pendingFields: number;
+  kind: string;
+  dryRun: boolean;
+}>;
+declare function migrateRuntimeSchema(input: {
+  dryRun: boolean;
+}): Promise<{
+  kind: string;
+  dryRun: boolean;
+  pendingTables: number;
+  pendingFields: number;
+} | {
+  appliedTables: number;
+  appliedFields: number;
+  kind: string;
+  dryRun: boolean;
+  pendingTables?: undefined;
+  pendingFields?: undefined;
+}>;
+//#endregion
+//#region src/services/backup.d.ts
+declare function createBackup(store: ManagementStore, backupDir?: string): BackupRecord;
+declare function verifyBackup(store: ManagementStore, backupId: string): BackupRecord;
+/**
+ * Restore backup into an isolated target store path (does not clobber source unless same path).
+ */
+declare function restoreBackup(store: ManagementStore, backupId: string, targetPath: string): {
+  targetPath: string;
+  counts: Record<string, number>;
+  checksum: string;
+};
+declare function upgradeCheck(store: ManagementStore): {
+  current: string;
+  latest: string;
+  runtimeBaseline: string;
+  action: "none" | "upgrade_available" | "plan_required";
+  notes: string[];
+};
+declare function emptyIsolatedStorePath(path: string): void;
+//#endregion
+//#region src/services/backup-pg.d.ts
+type PostgresContainerSettings = {
+  container: string;
+  user: string;
+  database: string;
+};
+type PostgresRestoreOptions = {
+  retain?: boolean;
+};
+/** Settings for the Docker fallback used by the local Compose stack. */
+declare function postgresContainerSettings(env?: NodeJS.ProcessEnv): PostgresContainerSettings;
+/** Make backup material inaccessible to other local users, including existing directories. */
+declare function ensurePrivateBackupDirectory(path: string): void;
+/** Dumps and sidecar metadata are sensitive operational artifacts. */
+declare function secureBackupArtifact(path: string): void;
+declare function validateIsolatedRestoreDatabaseName(candidate: string, activeDatabase?: string): string;
+declare function dockerDumpArgs(settings?: PostgresContainerSettings): string[];
+declare function dockerPsqlArgs(settings: PostgresContainerSettings, database: string, args: string[]): string[];
+declare function postgresBackupFailure(stage: "backup.create" | "backup.restore"): ClearanceError;
+declare function createPostgresBackup(store: ManagementStore, backupDir?: string): BackupRecord;
+/**
+ * Durable by construction (P2.2): validation + verified-flag write + audit
+ * commit in one awaited mutation, so a failed Postgres write rejects here
+ * instead of surfacing later (or never) via ready(). The CLI `backup verify`
+ * previously printed success while the queued write could still fail.
+ */
+declare function verifyPostgresBackup(store: ManagementStore, backupId: string): Promise<BackupRecord>;
+/**
+ * Restore dump into an isolated database name (creates DB if possible).
+ */
+declare function restorePostgresBackup(store: ManagementStore, backupId: string, isolatedDbName?: string, options?: PostgresRestoreOptions): Promise<{
+  database: string;
+  checksum: string;
+  verified: true;
+  retained: boolean;
+}>;
+declare function upgradeCheckWithDb(store: ManagementStore): Promise<{
+  current: string;
+  latest: string;
+  runtimeBaseline: string;
+  action: "none";
+  notes: string[];
+  authTableCounts: Record<string, number>;
+}>;
+//#endregion
+//#region src/services/fixtures.d.ts
+declare function fixturesRoot(): string;
+declare function loadJsonFixture<T = unknown>(relativePath: string): T;
+type SsoOidcFixture = {
+  matrix: string;
+  provider: string;
+  protocol: "oidc" | "saml";
+  issuer: string;
+  audience?: string;
+  domain?: string;
+  clientId?: string;
+  clientSecret?: string;
+  discovery: {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    [k: string]: unknown;
+  };
+};
+type ScimUsersFixture = {
+  provider: string;
+  users: Array<{
+    schemas: string[];
+    userName: string;
+    name?: {
+      formatted?: string;
+    };
+    emails?: Array<{
+      value: string;
+      primary?: boolean;
+    }>;
+    active?: boolean;
+  }>;
+};
+type AdversarialFixtureFile = {
+  cases: Array<{
+    id: string;
+    stage: string;
+    discovery?: Record<string, unknown>;
+    configuredIssuer?: string;
+    saml?: {
+      notBefore?: string;
+      notOnOrAfter?: string;
+    };
+    audience?: string;
+    configuredAudience?: string;
+  }>;
+};
+//#endregion
+//#region src/contracts/surfaces.d.ts
+/**
+ * Shared CLI ↔ API ↔ Console surface registry.
+ * Every management surface that reaches GA must appear here with all three contracts.
+ */
+interface ManagementSurface {
+  id: string;
+  cliCommand: string;
+  apiPath: string;
+  /** Route key in packages/clearance-console/public/app.js `routes` */
+  consoleRoute: string;
+}
+declare const MANAGEMENT_SURFACES: ManagementSurface[];
+declare function consoleRoutesFromContract(): string[];
+//#endregion
+//#region src/auth-bridge.d.ts
+declare function getAuthBundle(): ClearanceAuthBundle;
+/** Test helper — reset singleton between suites */
+declare function resetAuthBundle(): void;
+/** Release the shared runtime pool for short-lived callers such as the CLI. */
+declare function closeAuthBundle(): Promise<void>;
+declare function ensureAuthMigrated(): Promise<void>;
+declare function listUsersFromDb(): Promise<Principal[]>;
+declare function createUserInAuth(input: {
+  email: string;
+  name: string;
+  password?: string; /** When set, persists the runtime user into management with the same stable id */
+  managementStore?: ManagementStore;
+}): Promise<Principal>;
+/**
+ * Map an already-created runtime user into management (same stable id + scope).
+ * Prefer this after product signup so CLI/API/console see one identity.
+ */
+declare function bridgeRuntimeUserToManagement(store: ManagementStore, runtimeUser: {
+  id: string;
+  email: string;
+  name: string;
+  createdAt?: string | Date;
+  updatedAt?: string | Date;
+}, opts?: {
+  projectId?: string;
+  environmentId?: string;
+}): Promise<Principal>;
+declare function listOrgsFromDb(): Promise<Organization[]>;
+/**
+ * Create a runtime organization (and optional owner member). When userId is set,
+ * returns the exact Clearance owner membership id so management sync can keep
+ * the same stable membership id.
+ */
+declare function createOrgInAuth(input: {
+  name: string;
+  slug?: string;
+  userId?: string;
+}): Promise<Organization & {
+  ownerMembershipId?: string;
+}>;
+declare function countAuthTables(): Promise<Record<string, number>>;
+/** Ensure a system operator user exists for FK-backed SSO provider rows. */
+declare function ensureOperatorUser(): Promise<string>;
+/**
+ * Insert SSO provider, or reconcile an existing deterministic row.
+ * When `id` is provided (setup attempt path), retries read/reuse the same PK
+ * and fail closed on organization/provider/protocol/domain mismatch.
+ * Without `id`, generates a new id (CLI/operator path).
+ */
+declare function insertSsoProvider(input: {
+  /** Deterministic runtime/management id for setup-attempt recovery */id?: string;
+  providerId: string;
+  issuer: string;
+  domain: string;
+  organizationId?: string;
+  protocol: "saml" | "oidc";
+  oidc?: {
+    clientId: string;
+    clientSecret: string;
+  };
+  saml?: {
+    entryPoint: string;
+    cert: string;
+    audience?: string;
+  };
+}): Promise<{
+  id: string;
+  clientSecretFingerprint?: string;
+  reused?: boolean;
+}>;
+declare function deleteSsoProviderById(id: string): Promise<void>;
+/**
+ * Insert SCIM provider, or reconcile an existing deterministic row.
+ * On reuse, reconstructs the bearer handoff in-memory from encrypted stored
+ * material only (never persists plaintext). Without `id`, generates new ids.
+ */
+declare function insertScimProvider(input: {
+  /** Deterministic runtime/management id for setup-attempt recovery */id?: string;
+  providerId: string;
+  organizationId?: string;
+  token?: string;
+}): Promise<{
+  id: string;
+  token: string;
+  reused?: boolean;
+}>;
+declare function deleteScimProviderById(id: string): Promise<void>;
+/**
+ * Low-level runtime session rows. Never selects token / credential columns.
+ * Prefer listSessionsInAuth for scoped operator listing.
+ */
+declare function listSessionsFromDb(): Promise<Array<{
+  id: string;
+  userId: string;
+  createdAt: string;
+  expiresAt?: string;
+  ipAddress?: string;
+  userAgent?: string;
+}>>;
+/**
+ * List active runtime sessions under principal-derived scope.
+ * Only returns sessions whose userId maps to an in-scope management principal.
+ * Never exposes token material.
+ */
+declare function listSessionsInAuth(store: ManagementStore, opts?: {
+  scope?: ResourceScope;
+  limit?: number;
+}): Promise<SessionView[]>;
+/**
+ * Cursor-paginated runtime sessions (FOLLOW.md P2.3.1), CLI/API parity with
+ * the JSON-store listSessionsPage. Ordering: "createdAt" descending, then id
+ * descending — the same documented keyset. The cursor carries the row's
+ * full-precision createdAt text (Postgres microseconds), so the keyset row
+ * comparison cannot skip same-millisecond sessions.
+ */
+declare function listSessionsPageInAuth(store: ManagementStore, opts?: {
+  scope?: ResourceScope;
+  limit?: number; /** Opaque cursor from a previous page's nextCursor (fail-closed). */
+  cursor?: string;
+}): Promise<{
+  sessions: SessionView[];
+  nextCursor: string | null;
+}>;
+/** Load one safe runtime or revoked-tombstone session view without mutation. */
+declare function inspectSessionInAuth(store: ManagementStore, id: string, opts?: {
+  scope?: ResourceScope;
+}): Promise<SessionView>;
+/**
+ * Revoke one runtime session by stable id, coordinated with management tombstone + audit.
+ *
+ * Idempotent under authorized contract:
+ * - Active runtime row → delete + management revoked tombstone + audit
+ * - Already revoked management tombstone (no runtime row) → success, idempotent=true
+ * - Missing / cross-scope → SESSION_NOT_FOUND (fail closed)
+ */
+declare function revokeSessionInAuth(store: ManagementStore, id: string, input?: {
+  actor?: string;
+  source?: SessionSource;
+  scope?: ResourceScope;
+}): Promise<RevokeSessionResult>;
+type LifecycleSource = "cli" | "console" | "api" | "import" | "scim" | "system";
+/**
+ * Update name/email/status with runtime tables first-class in the same TX as
+ * the management principal snapshot (identical stable id).
+ */
+declare function updateUserInAuth(store: ManagementStore, id: string, input: {
+  name?: string;
+  email?: string;
+  status?: "active" | "disabled" | string;
+  actor?: string;
+  source?: LifecycleSource;
+  scope?: ResourceScope;
+}): Promise<Principal>;
+/**
+ * Disable principal: ban runtime user, revoke all runtime + management sessions,
+ * set management status=disabled, single success audit — all one transaction.
+ */
+declare function disableUserInAuth(store: ManagementStore, id: string, input?: {
+  actor?: string;
+  source?: LifecycleSource;
+  scope?: ResourceScope;
+}): Promise<Principal>;
+/**
+ * Soft-delete management principal and make runtime auth impossible:
+ * revoke sessions, strip credential accounts, ban + anonymize runtime email
+ * (preserve original email only on the management audit snapshot).
+ */
+declare function deleteUserInAuth(store: ManagementStore, id: string, input?: {
+  actor?: string;
+  source?: LifecycleSource;
+  scope?: ResourceScope;
+}): Promise<Principal>;
+/**
+ * Add membership with runtime member table + management snapshot + one audit
+ * in a single coordinated transaction. Preserves runtime membership ids when
+ * a matching Clearance row exists. Idempotent for active duplicates.
+ */
+declare function addMemberInAuth(store: ManagementStore, input: {
+  organizationId: string;
+  principalId: string;
+  role?: string;
+  source?: MembershipSource;
+  actor?: string;
+  auditSource?: MembershipActorSource;
+  scope?: ResourceScope;
+}): Promise<Membership>;
+/**
+ * Update membership role with runtime + management + single audit in one TX.
+ * Missing/divergent pairs fail closed after deterministic reconcile attempts.
+ */
+declare function updateMemberInAuth(store: ManagementStore, id: string, input: {
+  role: string;
+  actor?: string;
+  auditSource?: MembershipActorSource;
+  scope?: ResourceScope;
+}): Promise<Membership>;
+/**
+ * Remove membership: soft-remove management + hard-delete runtime member +
+ * one success audit in a single coordinated transaction.
+ */
+declare function removeMemberInAuth(store: ManagementStore, id: string, input?: {
+  actor?: string;
+  auditSource?: MembershipActorSource;
+  scope?: ResourceScope;
+}): Promise<Membership>;
+type OrgLifecycleSource = "cli" | "console" | "api" | "import" | "system";
+/**
+ * Update organization name and/or slug with identical values in Clearance
+ * runtime and management snapshot (stable organization id) in one transaction.
+ *
+ * Management values are authoritative for the intended final state. A true
+ * idempotent no-op is allowed only when both runtime and management already
+ * match those final values (returns current org, no audit). If runtime is
+ * divergent, reconcile it to the management-authoritative finals in the same
+ * coordinated transaction and emit exactly one update/reconcile audit.
+ * Missing runtime org, cross-scope id, invalid slug, or slug conflict fails
+ * closed with zero writes and no success audit.
+ */
+declare function updateOrganizationInAuth(store: ManagementStore, id: string, input: {
+  name?: string;
+  slug?: string;
+  actor?: string;
+  source?: OrgLifecycleSource;
+  scope?: ResourceScope;
+}): Promise<Organization>;
+/**
+ * Archive organization with coordinated runtime + management transaction.
+ *
+ * Behavior (hard-delete runtime, management tombstone):
+ * - Hard-delete all runtime `member` rows for the org, then the runtime
+ *   `organization` row (invitations cascade via FK). Runtime org cannot be used.
+ * - Preserve management organization row with status=archived (tombstone keeps
+ *   the stable organization id for audit/recovery).
+ * - Soft-remove all active management memberships for the org (status=removed).
+ * - Exactly one success audit on first archive; re-archive is idempotent with
+ *   no duplicate audit.
+ * - Owner/last-owner membership invariants are intentionally not enforced: archive
+ *   is a deliberate org-level lifecycle end, not a membership remove.
+ * - Dry-run / missing confirm preview without mutation (same contract as management).
+ * - Active org missing from runtime fails closed (ORG_RUNTIME_NOT_FOUND).
+ * - Already-archived + missing runtime → success, idempotent=true.
+ */
+declare function archiveOrganizationInAuth(store: ManagementStore, id: string, input?: {
+  dryRun?: boolean; /** Required for mutation. CLI maps --yes → confirm=true. */
+  confirm?: boolean;
+  actor?: string;
+  source?: OrgLifecycleSource;
+  scope?: ResourceScope;
+}): Promise<ArchiveOrganizationResult>;
+//#endregion
+export { AUDIT_MAX_EVENTS_DEFAULT, AUDIT_MAX_EVENTS_MAX, AUDIT_MAX_EVENTS_MIN, AUDIT_PRUNED_ACTION, AdversarialFixtureFile, ApiKey, ApiKeyView, ArchiveOrganizationResult, AssignableRole, AuditEvent, AuditEventInput, BUILT_IN_ROLE_SLUGS, BackupRecord, BuiltInRoleSlug, CLEARANCE_RELEASE_VERSION, ClearanceError, type CommitSetupLinkInput, ConfigRecord, ConformanceMode, CreateStoreOptions, CreatedApiKey, CredentialKeyring, CustomRole, DataStoreSnapshot, DiagnosticTrace, DirectoryConnection, DoctorCheck, EVENTS_EXPORT_DEFAULT_LIMIT, EVENTS_EXPORT_FORMATS, EVENTS_EXPORT_MAX_LIMIT, EVENTS_LIST_DEFAULT_PAGE_LIMIT, EVENTS_LIST_MAX_PAGE_LIMIT, EVENTS_TAIL_DEFAULT_LIMIT, EVENTS_TAIL_MAX_LIMIT, EncryptedCredential, Environment, EnvironmentInspectResult, EnvironmentLocalStatus, EnvironmentPromoteBlocker, EnvironmentPromotePlanStep, EnvironmentPromoteResult, EventInspectResult, EventsExportEnvelope, EventsExportFormat, EventsExportOptions, EventsTailCursor, EventsTailFilter, FORBIDDEN_DEFAULT_SECRETS, IDEMPOTENCY_DEFAULT_TTL_MS, IdempotencyBackend, IdempotencyRecord, IdentityConnection, IdentityProtocol, JsonStore, LIVE_CONFORMANCE_MODE, LIVE_EVIDENCE_LABEL, LegacyExportFixture, LiveProbeOptions, LiveProbeResult, LocalOidcSession, MANAGEMENT_SURFACES, ManagementStore, ManagementSurface, MemberImportFormat, MemberImportPlan, MemberImportPlanRow, MemberImportResult, MemberImportRowResult, Membership, MembershipActorSource, MembershipSource, MigrationPlan, MigrationPreview, ORGS_LIST_DEFAULT_PAGE_LIMIT, ORGS_LIST_MAX_PAGE_LIMIT, Organization, PageCursorKey, PageOrder, PageSurface, type PgStore, PostgresRestoreOptions, Principal, Project, REPLAYABLE_TRACE_SUBSYSTEMS, ReadinessCheck, ReadinessReport, type RedeemSetupLinkInput, type ReleaseSetupLinkInput, ReplayDiagnosticOptions, ReplayDiagnosticResult, ReplayableTraceSubsystem, type ReserveSetupLinkResult, ResourceId, ResourcePage, ResourceScope, RevokeSessionResult, RuntimeOrganizationIdentity, RuntimeSchemaPlanResult, RuntimeUserIdentity, SCIM_FIXTURE_MODE, SCIM_LOCAL_PROTOCOL_EVIDENCE, SCIM_REAL_FIXTURE_MODE, SETUP_RESERVATION_TTL_MS, SSO_FIXTURE_MODE, SSO_LOCAL_EVIDENCE_LABEL, SSO_LOCAL_PROTOCOL_MODE, SSO_MATRIX_NOT_CERTIFIED, SSO_REAL_FIXTURE_MODE, STORE_SCHEMA_VERSION, ScimActorSource, ScimMutationOpts, ScimProbeOptions, ScimProbeOutcome, ScimUserPayload, ScimUsersFixture, ScopedResource, SessionRecord, SessionSource, SessionView, SetupCapability, type SetupKind, SsoActorSource, SsoCreateInput, SsoMutationOpts, SsoOidcFixture, SsoTestFixture, SsoTestOptions, USERS_EXPORT_DEFAULT_LIMIT, USERS_EXPORT_FORMATS, USERS_EXPORT_MAX_LIMIT, USERS_LIST_DEFAULT_PAGE_LIMIT, USERS_LIST_MAX_PAGE_LIMIT, UsersExportEnvelope, UsersExportFormat, UsersExportOptions, WRITE_ONLY_SECRET_FIELDS, WriteExportArtifactCodes, addMember, addMemberInAuth, appendAuditEvent, archiveOrganization, archiveOrganizationInAuth, assertClientScopeHeaders, assertCredentialKeyConfigured, assertIdempotencyKeyValid, assertLiveEndpoint, assertMigrationRunnable, assertOwnerInvariant, assertProductionCredentialKey, assertProductionSecret, assertResourceInScope, assertSessionPrincipalInScope, auditMaxEvents, beginEventsTail, bridgeRuntimeUserToManagement, buildAuditEvent, buildAuthorizationUrl, builtInRoleId, checkScimConnection, closeAuthBundle, commitSetupLink, configureSsoConnection, consoleRoutesFromContract, correlationId, countAuthTables, createApiKey, createBackup, createEnvironment, createIdempotencyBackend, createLocalOidcIssuerFixture, createLocalScimFixtureServer, createManagementStore, createOrgInAuth, createOrganization, createPgStore, createPostgresBackup, createProject, createRole, createScimConnection, createScimConnectionReal, createSession, createSetupLink, createSsoConnection, createSsoConnectionReal, createUser, createUserInAuth, decodeJwtPayload, decodePageCursor, decryptCredential, defaultDataPath, deleteScimProviderById, deleteSsoProviderById, deleteUser, deleteUserInAuth, deriveSetupConnectionIds, deriveSetupReservationId, diffConfig, disableScimConnection, disableScimConnectionReal, disableSsoConnection, disableSsoConnectionReal, disableUser, disableUserInAuth, dockerDumpArgs, dockerPsqlArgs, emptyIsolatedStorePath, emptySnapshot, encodePageCursor, encryptCredential, enforceAuditRetention, ensureAuthMigrated, ensureOperatorUser, ensurePrivateBackupDirectory, executeMemberImportPlan, exportEvents, exportUsers, findActiveMembership, fingerprint, fingerprintCredential, fingerprintIdempotentRequest, fixturesRoot, generatePkcePair, generateRuntimeSchema, getAuthBundle, getCredentialKeyring, getLatestReadiness, getRuntimeSchemaStatus, idempotencyConflictError, initProject, insertScimProvider, insertSsoProvider, inspectApiKey, inspectEnvironment, inspectEvent, inspectMembership, inspectOrganization, inspectRole, inspectScimConnection, inspectScimTrace, inspectSession, inspectSessionInAuth, inspectSsoConnection, inspectUser, isBuiltInRoleSlug, isClearanceError, isCredentialEnvelope, isDevelopmentLike, isForbiddenDefaultSecret, isManagementStore, isReplayableTraceSubsystem, isSecretLikeConfigEntry, isSecretLikeConfigKey, listApiKeys, listEnvironments, listEvents, listEventsPage, listMembers, listOrganizations, listOrganizationsPage, listOrgsFromDb, listProjects, listRoles, listScimConnections, listSessions, listSessionsFromDb, listSessionsInAuth, listSessionsPage, listSessionsPageInAuth, listSetupLinks, listSsoConnections, listUsers, listUsersFromDb, listUsersPage, loadJsonFixture, loadLegacyFixture, migrateRuntimeSchema, migrationStatus, newId, normalizeAndValidateApiKeyScopes, normalizeAndValidatePermissions, normalizeEventsExportBefore, normalizeEventsExportFormat, normalizeEventsExportLimit, normalizeEventsTailLimit, normalizePageLimit, normalizeSessionLimit, normalizeSnapshot, normalizeUsersExportFormat, normalizeUsersExportLimit, normalizeUsersExportStatus, nowIso, overviewStats, paginateByCreatedAt, parseConfigJson, parseCorsOrigins, parseCredentialEnvelope, parseUserStatusInput, pgStoreId, planEnvironmentCreate, planMemberImport, planMigration, planProjectCreate, planRuntimeSchema, pollEventsTail, postgresBackupFailure, postgresContainerSettings, previewMigration, probeOutcomeToError, probeScimEndpoint, promoteEnvironment, publicConfig, publicDirectoryConnection, publicIdentityConnection, recordEvent, redactRecord, redactValue, redeemSetupLink, releaseSetupLink, removeMember, removeMemberInAuth, replayDiagnosticTrace, replayScimTrace, requireOperatorToken, reserveSetupLink, resetAuthBundle, resolveAssignableRole, resolveCredentialKeyring, resolveIdempotencyTtlMs, resolveMembershipId, resolveOperatorScope, resolveScimConnection, resolveSsoConnection, restoreBackup, restorePostgresBackup, revokeApiKey, revokeSession, revokeSessionInAuth, revokeSetupLink, rollbackMigration, rollbackMigrationDurable, rotateApiKey, rotateCredential, rotateScimCredential, rotateSsoCredential, runDoctor, runMigration, runMigrationDurable, runReadinessCheck, runSsoMatrix, sanitizeAuditEvent, sanitizePrincipalForExport, sanitizeSessionView, scopeFilter, secureBackupArtifact, selectEventsForExport, selectUsersForExport, setConfig, sortEventsDeterministic, sortUsersDeterministic, syncRuntimeOrganizationToManagementDurable, syncRuntimeUserToManagement, syncRuntimeUserToManagementDurable, testScimConnection, testScimConnectionLive, testScimConnectionReal, testSsoConnection, testSsoConnectionLive, testSsoConnectionReal, toSessionView, updateMember, updateMemberInAuth, updateOrganization, updateOrganizationInAuth, updateRole, updateUser, updateUserInAuth, upgradeCheck, upgradeCheckWithDb, validateApiKeyName, validateConfig, validateCurrentConfig, validateIsolatedRestoreDatabaseName, validateRole, validateRoleName, validateRoleSlug, validateSamlProviderConfig, verifyBackup, verifyMigration, verifyMigrationDurable, verifyPostgresBackup, verifySsoOidcLocalProtocol, writeExportArtifact };