@hasna/tenants 0.1.0

package/dist/db.js

@@ -0,0 +1,480 @@
+// @bun
+// src/generated/storage-kit/mode.ts
+var DEPRECATED_STORAGE_MODE_ALIASES = [
+  "remote",
+  "hybrid",
+  "self_hosted"
+];
+function normalizeStorageMode(value) {
+  const normalized = value.trim().toLowerCase().replace(/-/g, "_");
+  if (normalized === "local")
+    return { mode: "local", deprecatedAlias: null };
+  if (normalized === "cloud")
+    return { mode: "cloud", deprecatedAlias: null };
+  if (DEPRECATED_STORAGE_MODE_ALIASES.includes(normalized)) {
+    return { mode: "cloud", deprecatedAlias: normalized };
+  }
+  throw new Error(`Unknown storage mode: ${value}. Use local or cloud.`);
+}
+function envToken(name) {
+  return name.toUpperCase().replace(/-/g, "_");
+}
+function storageEnvKeys(name) {
+  const token = envToken(name);
+  return {
+    modeKeys: [`HASNA_${token}_STORAGE_MODE`, `${token}_STORAGE_MODE`],
+    databaseUrlKeys: [`HASNA_${token}_DATABASE_URL`, `${token}_DATABASE_URL`]
+  };
+}
+function firstEnv(env, keys) {
+  for (const key of keys) {
+    const value = env[key]?.trim();
+    if (value)
+      return { key, value };
+  }
+  return null;
+}
+function resolveStorageMode(name, env = process.env) {
+  const { modeKeys, databaseUrlKeys } = storageEnvKeys(name);
+  const dbHit = firstEnv(env, databaseUrlKeys);
+  const databaseUrlPresent = Boolean(dbHit);
+  const databaseUrlSource = dbHit ? dbHit.key : null;
+  const modeHit = firstEnv(env, modeKeys);
+  if (!modeHit) {
+    return {
+      mode: "local",
+      source: "default",
+      deprecatedAlias: null,
+      databaseUrlPresent,
+      databaseUrlSource,
+      warning: null
+    };
+  }
+  const { mode, deprecatedAlias } = normalizeStorageMode(modeHit.value);
+  const warnings = [];
+  if (deprecatedAlias) {
+    warnings.push(`Deprecated storage mode '${deprecatedAlias}' from ${modeHit.key} is treated as 'cloud'. Set ${modeKeys[0]}=cloud instead.`);
+  }
+  if (mode === "cloud" && !databaseUrlPresent) {
+    warnings.push(`cloud mode needs ${databaseUrlKeys[0]} (PURE REMOTE: reads and writes go to cloud Postgres).`);
+  }
+  if (modeHit.key !== modeKeys[0]) {
+    warnings.push(`Using alias env ${modeHit.key}; the canonical key is ${modeKeys[0]}.`);
+  }
+  return {
+    mode,
+    source: modeHit.key,
+    deprecatedAlias,
+    databaseUrlPresent,
+    databaseUrlSource,
+    warning: warnings.length > 0 ? warnings.join(" ") : null
+  };
+}
+function resolveDatabaseUrl(name, env = process.env) {
+  const { databaseUrlKeys } = storageEnvKeys(name);
+  const hit = firstEnv(env, databaseUrlKeys);
+  return hit ? hit.value : null;
+}
+// src/generated/storage-kit/tls.ts
+import { readFileSync } from "fs";
+function sslModeFromConnectionString(connectionString) {
+  const queryStart = connectionString.indexOf("?");
+  const params = new URLSearchParams(queryStart === -1 ? "" : connectionString.slice(queryStart + 1));
+  const sslmode = params.get("sslmode")?.trim().toLowerCase();
+  if (sslmode) {
+    switch (sslmode) {
+      case "disable":
+      case "prefer":
+      case "require":
+      case "verify-ca":
+      case "verify-full":
+        return sslmode;
+      case "allow":
+        return "prefer";
+      default:
+        throw new Error(`Unknown sslmode '${sslmode}' in connection string.`);
+    }
+  }
+  const ssl = params.get("ssl")?.trim().toLowerCase();
+  if (ssl && ["1", "true", "yes", "on", "require"].includes(ssl))
+    return "require";
+  return "disable";
+}
+function loadCaBundle(options) {
+  const env = options.env ?? process.env;
+  if (options.ca && options.ca.trim())
+    return options.ca;
+  const path = options.caCertPath ?? env.PGSSLROOTCERT ?? env.NODE_EXTRA_CA_CERTS;
+  if (path && path.trim())
+    return readFileSync(path.trim(), "utf8");
+  return null;
+}
+function resolveTlsConfig(connectionString, options = {}) {
+  const mode = sslModeFromConnectionString(connectionString);
+  if (mode === "disable" || mode === "prefer") {
+    return;
+  }
+  const ca = loadCaBundle(options);
+  if (mode === "require") {
+    return ca ? { rejectUnauthorized: false, ca } : { rejectUnauthorized: false };
+  }
+  if (!ca) {
+    throw new Error(`sslmode=${mode} requires a CA bundle. Set PGSSLROOTCERT (or pass caCertPath/ca) to the ` + `Amazon RDS global bundle: https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem`);
+  }
+  return { rejectUnauthorized: true, ca };
+}
+// src/generated/storage-kit/query.ts
+function wrapExecutor(executor) {
+  return {
+    async query(sql, params) {
+      const result = await executor.query(sql, params);
+      return { rows: result.rows, rowCount: result.rowCount ?? result.rows.length };
+    },
+    async many(sql, params) {
+      const result = await executor.query(sql, params);
+      return result.rows;
+    },
+    async get(sql, params) {
+      const result = await executor.query(sql, params);
+      return result.rows[0] ?? null;
+    },
+    async one(sql, params) {
+      const result = await executor.query(sql, params);
+      if (result.rows.length !== 1) {
+        throw new Error(`Expected exactly one row, got ${result.rows.length}.`);
+      }
+      return result.rows[0];
+    },
+    async execute(sql, params) {
+      await executor.query(sql, params);
+    }
+  };
+}
+function createQueryClient(pool) {
+  const base = wrapExecutor(pool);
+  return {
+    ...base,
+    pool,
+    async transaction(fn) {
+      const client = await pool.connect();
+      try {
+        await client.query("BEGIN");
+        const result = await fn(wrapExecutor(client));
+        await client.query("COMMIT");
+        return result;
+      } catch (error) {
+        try {
+          await client.query("ROLLBACK");
+        } catch {}
+        throw error;
+      } finally {
+        client.release();
+      }
+    },
+    async close() {
+      await pool.end();
+    }
+  };
+}
+// src/generated/storage-kit/pool.ts
+import pg from "pg";
+function createPgPool(options) {
+  const ssl = resolveTlsConfig(options.connectionString, {
+    ...options.ca !== undefined ? { ca: options.ca } : {},
+    ...options.caCertPath !== undefined ? { caCertPath: options.caCertPath } : {},
+    ...options.env !== undefined ? { env: options.env } : {}
+  });
+  const config = { connectionString: options.connectionString };
+  if (ssl !== undefined)
+    config.ssl = ssl;
+  if (options.max !== undefined)
+    config.max = options.max;
+  if (options.idleTimeoutMillis !== undefined)
+    config.idleTimeoutMillis = options.idleTimeoutMillis;
+  if (options.connectionTimeoutMillis !== undefined)
+    config.connectionTimeoutMillis = options.connectionTimeoutMillis;
+  if (options.applicationName !== undefined)
+    config.application_name = options.applicationName;
+  return new pg.Pool(config);
+}
+function createCloudPoolFromEnv(appName, options = {}) {
+  const env = options.env ?? process.env;
+  const resolution = resolveStorageMode(appName, env);
+  if (resolution.mode !== "cloud") {
+    throw new Error(`createCloudPoolFromEnv requires ${appName} storage mode 'cloud', got '${resolution.mode}'. ` + `Set HASNA_${appName.toUpperCase().replace(/-/g, "_")}_STORAGE_MODE=cloud.`);
+  }
+  const connectionString = resolveDatabaseUrl(appName, env);
+  if (!connectionString) {
+    throw new Error(`cloud mode for ${appName} needs a database URL. Set ` + `HASNA_${appName.toUpperCase().replace(/-/g, "_")}_DATABASE_URL.`);
+  }
+  const pool = createPgPool({
+    connectionString,
+    ...options.ca !== undefined ? { ca: options.ca } : {},
+    ...options.caCertPath !== undefined ? { caCertPath: options.caCertPath } : {},
+    env,
+    ...options.max !== undefined ? { max: options.max } : {},
+    ...options.idleTimeoutMillis !== undefined ? { idleTimeoutMillis: options.idleTimeoutMillis } : {},
+    ...options.connectionTimeoutMillis !== undefined ? { connectionTimeoutMillis: options.connectionTimeoutMillis } : {},
+    ...options.applicationName !== undefined ? { applicationName: options.applicationName } : {}
+  });
+  return {
+    client: createQueryClient(pool),
+    connectionSource: resolution.databaseUrlSource ?? "unknown"
+  };
+}
+// src/generated/storage-kit/migrations.ts
+import { createHash } from "crypto";
+var DEFAULT_MIGRATION_LEDGER_TABLE = "schema_migrations";
+function checksumSql(sql) {
+  const normalized = sql.trim().replace(/\r\n/g, `
+`);
+  return `sha256:${createHash("sha256").update(normalized).digest("hex")}`;
+}
+function defineMigration(id, sql) {
+  return Object.freeze({ id, sql: sql.trim(), checksum: checksumSql(sql) });
+}
+
+class MigrationLedger {
+  client;
+  migrations;
+  ledgerTable;
+  constructor(client, migrations, options = {}) {
+    this.client = client;
+    this.migrations = migrations;
+    this.ledgerTable = options.ledgerTable ?? DEFAULT_MIGRATION_LEDGER_TABLE;
+    const seen = new Set;
+    for (const migration of migrations) {
+      if (seen.has(migration.id))
+        throw new Error(`Duplicate migration id: ${migration.id}`);
+      seen.add(migration.id);
+    }
+  }
+  async ensureLedger() {
+    await this.client.execute(`CREATE TABLE IF NOT EXISTS ${this.ledgerTable} (
+         id TEXT PRIMARY KEY,
+         checksum TEXT NOT NULL,
+         applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+       )`);
+  }
+  async listApplied() {
+    await this.ensureLedger();
+    return this.readApplied();
+  }
+  async readApplied() {
+    const rows = await this.client.many(`SELECT id, checksum, applied_at FROM ${this.ledgerTable} ORDER BY id ASC`);
+    return rows.map((row) => ({
+      id: row.id,
+      checksum: row.checksum,
+      appliedAt: row.applied_at instanceof Date ? row.applied_at.toISOString() : String(row.applied_at)
+    }));
+  }
+  buildPlan(applied) {
+    const known = new Set(this.migrations.map((m) => m.id));
+    for (const row of applied) {
+      if (!known.has(row.id)) {
+        throw new Error(`Applied migration '${row.id}' is not recognized by this build (downgrade?).`);
+      }
+    }
+    const appliedById = new Map(applied.map((row) => [row.id, row]));
+    for (const migration of this.migrations) {
+      const existing = appliedById.get(migration.id);
+      if (existing && existing.checksum !== migration.checksum) {
+        throw new Error(`Migration checksum mismatch for '${migration.id}': the SQL changed after it was applied.`);
+      }
+    }
+    return this.migrations.map((migration) => ({
+      migration,
+      state: appliedById.has(migration.id) ? "already_applied" : "pending"
+    }));
+  }
+  async migrate(opts = {}) {
+    const dryRun = opts.dryRun === true;
+    await this.ensureLedger();
+    const applied = await this.readApplied();
+    const plan = this.buildPlan(applied);
+    if (dryRun)
+      return { dryRun, applied, plan };
+    for (const item of plan) {
+      if (item.state === "already_applied")
+        continue;
+      await this.client.execute(item.migration.sql);
+      await this.client.execute(`INSERT INTO ${this.ledgerTable} (id, checksum, applied_at) VALUES ($1, $2, now())`, [item.migration.id, item.migration.checksum]);
+    }
+    return { dryRun, applied: await this.readApplied(), plan };
+  }
+}
+// src/generated/storage-kit/health.ts
+async function checkHealth(client) {
+  const start = Date.now();
+  try {
+    await client.get("SELECT 1 AS ok");
+    return { ok: true, latencyMs: Date.now() - start };
+  } catch (error) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function checkReady(client, migrations, options = {}) {
+  const start = Date.now();
+  try {
+    const ledger = new MigrationLedger(client, migrations, options);
+    const result = await ledger.migrate({ dryRun: true });
+    const pending = result.plan.filter((item) => item.state === "pending").map((item) => item.migration.id);
+    return { ok: pending.length === 0, latencyMs: Date.now() - start, pendingMigrations: pending };
+  } catch (error) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      pendingMigrations: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+// src/migrations.ts
+import { apiKeyMigrations } from "@hasna/contracts/auth";
+
+// src/idp/migrations.ts
+var TENANTS_TABLE = "tenants";
+var USERS_TABLE = "users";
+var SERVICE_PRINCIPALS_TABLE = "service_principals";
+var MEMBERSHIPS_TABLE = "memberships";
+var SESSIONS_TABLE = "sessions";
+var AUTH_CHALLENGES_TABLE = "auth_challenges";
+var JWT_SIGNING_KEYS_TABLE = "jwt_signing_keys";
+function idpMigrations(apiKeysTable) {
+  return [
+    defineMigration("tenants_0001_tenants", `CREATE TABLE IF NOT EXISTS ${TENANTS_TABLE} (
+         id          UUID PRIMARY KEY,
+         slug        TEXT UNIQUE NOT NULL,
+         name        TEXT NOT NULL,
+         kind        TEXT NOT NULL DEFAULT 'org',
+         parent_id   UUID REFERENCES ${TENANTS_TABLE}(id),
+         status      TEXT NOT NULL DEFAULT 'active',
+         identity_id TEXT,
+         metadata    JSONB NOT NULL DEFAULT '{}'::jsonb,
+         created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+         updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+       )`),
+    defineMigration("tenants_0002_users", `CREATE TABLE IF NOT EXISTS ${USERS_TABLE} (
+         id            UUID PRIMARY KEY,
+         kind          TEXT NOT NULL,
+         email         TEXT UNIQUE,
+         display_name  TEXT,
+         identity_id   TEXT,
+         home_tenant_id UUID REFERENCES ${TENANTS_TABLE}(id),
+         auth_method   TEXT,
+         password_hash TEXT,
+         status        TEXT NOT NULL DEFAULT 'active',
+         metadata      JSONB NOT NULL DEFAULT '{}'::jsonb,
+         created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+         updated_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+         email_verified_at TIMESTAMPTZ
+       )`),
+    defineMigration("tenants_0003_service_principals", `CREATE TABLE IF NOT EXISTS ${SERVICE_PRINCIPALS_TABLE} (
+         id            UUID PRIMARY KEY,
+         tenant_id     UUID NOT NULL REFERENCES ${TENANTS_TABLE}(id),
+         kind          TEXT NOT NULL DEFAULT 'machine',
+         display_name  TEXT,
+         identity_id   TEXT,
+         enrollment_secret_ref TEXT,
+         status        TEXT NOT NULL DEFAULT 'active',
+         metadata      JSONB NOT NULL DEFAULT '{}'::jsonb,
+         created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+         last_seen_at  TIMESTAMPTZ
+       )`),
+    defineMigration("tenants_0004_memberships", `CREATE TABLE IF NOT EXISTS ${MEMBERSHIPS_TABLE} (
+         id             BIGSERIAL PRIMARY KEY,
+         tenant_id      UUID NOT NULL REFERENCES ${TENANTS_TABLE}(id),
+         principal_id   UUID NOT NULL,
+         principal_type TEXT NOT NULL,
+         role           TEXT NOT NULL,
+         scopes         JSONB NOT NULL DEFAULT '[]'::jsonb,
+         status         TEXT NOT NULL DEFAULT 'active',
+         created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
+         UNIQUE (tenant_id, principal_id, principal_type)
+       )`),
+    defineMigration("tenants_0005_sessions", `CREATE TABLE IF NOT EXISTS ${SESSIONS_TABLE} (
+         id         UUID PRIMARY KEY,
+         user_id    UUID REFERENCES ${USERS_TABLE}(id),
+         tenant_id  UUID REFERENCES ${TENANTS_TABLE}(id),
+         token_hash TEXT UNIQUE NOT NULL,
+         method     TEXT,
+         issued_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+         expires_at TIMESTAMPTZ,
+         revoked_at TIMESTAMPTZ,
+         ip         TEXT,
+         user_agent TEXT
+       )`),
+    defineMigration("tenants_0006_auth_challenges", `CREATE TABLE IF NOT EXISTS ${AUTH_CHALLENGES_TABLE} (
+         id          UUID PRIMARY KEY,
+         email       TEXT NOT NULL,
+         code_hash   TEXT NOT NULL,
+         purpose     TEXT NOT NULL,
+         expires_at  TIMESTAMPTZ NOT NULL,
+         consumed_at TIMESTAMPTZ,
+         attempts    INT NOT NULL DEFAULT 0,
+         created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+       )`),
+    defineMigration("tenants_0007_auth_challenges_email_idx", `CREATE INDEX IF NOT EXISTS ${AUTH_CHALLENGES_TABLE}_email_idx
+         ON ${AUTH_CHALLENGES_TABLE} (email, purpose, created_at DESC)`),
+    defineMigration("tenants_0008_jwt_signing_keys", `CREATE TABLE IF NOT EXISTS ${JWT_SIGNING_KEYS_TABLE} (
+         kid         TEXT PRIMARY KEY,
+         alg         TEXT NOT NULL DEFAULT 'EdDSA',
+         public_jwk  JSONB NOT NULL,
+         private_jwk JSONB NOT NULL,
+         status      TEXT NOT NULL DEFAULT 'active',
+         created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+         retired_at  TIMESTAMPTZ
+       )`),
+    defineMigration("tenants_0009_memberships_principal_idx", `CREATE INDEX IF NOT EXISTS ${MEMBERSHIPS_TABLE}_principal_idx
+         ON ${MEMBERSHIPS_TABLE} (principal_id, principal_type)`),
+    defineMigration("tenants_0010_api_keys_tenant", `ALTER TABLE ${apiKeysTable} ADD COLUMN IF NOT EXISTS tenant_id UUID;
+       ALTER TABLE ${apiKeysTable} ADD COLUMN IF NOT EXISTS user_id UUID;
+       ALTER TABLE ${apiKeysTable} ADD COLUMN IF NOT EXISTS principal_type TEXT;`),
+    defineMigration("tenants_0011_api_keys_tenant_idx", `CREATE INDEX IF NOT EXISTS ${apiKeysTable}_tenant_idx ON ${apiKeysTable} (tenant_id)`)
+  ];
+}
+
+// src/migrations.ts
+var API_KEYS_TABLE = "api_keys";
+function tenantsMigrations() {
+  return [
+    ...apiKeyMigrations(API_KEYS_TABLE).map((m) => defineMigration(m.id, m.sql)),
+    ...idpMigrations(API_KEYS_TABLE)
+  ];
+}
+
+// src/db.ts
+var TENANTS_APP_NAME = "tenants";
+function createCloudClient(options = {}) {
+  const { client, connectionSource } = createCloudPoolFromEnv(TENANTS_APP_NAME, {
+    applicationName: options.applicationName ?? "tenants-serve"
+  });
+  return {
+    client,
+    connectionSource,
+    close: async () => {
+      await client.close();
+    }
+  };
+}
+async function runTenantsMigrations(client, opts = {}) {
+  const ledger = new MigrationLedger(client, tenantsMigrations());
+  return ledger.migrate(opts);
+}
+async function cloudHealth(client) {
+  return checkHealth(client);
+}
+async function cloudReady(client) {
+  return checkReady(client, tenantsMigrations());
+}
+export {
+  runTenantsMigrations,
+  createCloudClient,
+  cloudReady,
+  cloudHealth,
+  TENANTS_APP_NAME
+};

package/dist/generated/storage-kit/health.d.ts

@@ -0,0 +1,19 @@
+import type { TypedQueryClient } from "./query.js";
+import { type Migration, type MigrationRunnerOptions } from "./migrations.js";
+export interface HealthResult {
+    ok: boolean;
+    /** Round-trip latency of the probe query, in milliseconds. */
+    latencyMs: number;
+    error?: string;
+}
+/** Cheap reachability probe: `SELECT 1`. Never throws — reports `ok: false`. */
+export declare function checkHealth(client: TypedQueryClient): Promise<HealthResult>;
+export interface ReadyResult extends HealthResult {
+    /** Migration ids that are defined but not yet applied. */
+    pendingMigrations: string[];
+}
+/**
+ * Readiness probe: reachable AND fully migrated. Reports `ok: false` with the
+ * list of pending migration ids when the schema is behind.
+ */
+export declare function checkReady(client: TypedQueryClient, migrations: readonly Migration[], options?: MigrationRunnerOptions): Promise<ReadyResult>;

package/dist/generated/storage-kit/index.d.ts

@@ -0,0 +1,7 @@
+export declare const KIT_VERSION = "0.4.2";
+export * from "./mode.js";
+export * from "./tls.js";
+export * from "./query.js";
+export * from "./pool.js";
+export * from "./migrations.js";
+export * from "./health.js";

package/dist/generated/storage-kit/migrations.d.ts

@@ -0,0 +1,47 @@
+import type { TypedQueryClient } from "./query.js";
+/** Default ledger table name. Override per app if a legacy name exists. */
+export declare const DEFAULT_MIGRATION_LEDGER_TABLE = "schema_migrations";
+export interface Migration {
+    readonly id: string;
+    readonly sql: string;
+    readonly checksum: string;
+}
+export type MigrationState = "already_applied" | "pending";
+export interface MigrationPlanItem {
+    readonly migration: Migration;
+    readonly state: MigrationState;
+}
+export interface AppliedMigration {
+    readonly id: string;
+    readonly checksum: string;
+    readonly appliedAt: string;
+}
+export interface MigrationResult {
+    readonly dryRun: boolean;
+    readonly applied: AppliedMigration[];
+    readonly plan: MigrationPlanItem[];
+}
+/** Stable sha256 checksum for a migration's SQL text. */
+export declare function checksumSql(sql: string): string;
+/** Freeze a migration definition, computing its checksum from the SQL. */
+export declare function defineMigration(id: string, sql: string): Migration;
+export interface MigrationRunnerOptions {
+    ledgerTable?: string;
+}
+export declare class MigrationLedger {
+    private readonly client;
+    private readonly migrations;
+    private readonly ledgerTable;
+    constructor(client: TypedQueryClient, migrations: readonly Migration[], options?: MigrationRunnerOptions);
+    ensureLedger(): Promise<void>;
+    listApplied(): Promise<AppliedMigration[]>;
+    private readApplied;
+    /** Compute the migration plan and guard against drift/downgrade. */
+    private buildPlan;
+    /** Apply all pending migrations. With `dryRun`, report the plan only. */
+    migrate(opts?: {
+        dryRun?: boolean;
+    }): Promise<MigrationResult>;
+}
+/** Convenience: build a ledger and run all pending migrations. */
+export declare function createMigrationLedger(client: TypedQueryClient, migrations: readonly Migration[], options?: MigrationRunnerOptions): MigrationLedger;

package/dist/generated/storage-kit/mode.d.ts

@@ -0,0 +1,47 @@
+export declare const STORAGE_MODES: readonly ["local", "cloud"];
+export type StorageMode = (typeof STORAGE_MODES)[number];
+export declare const DEPRECATED_STORAGE_MODE_ALIASES: readonly ["remote", "hybrid", "self_hosted"];
+export type Env = Record<string, string | undefined>;
+export interface StorageModeNormalization {
+    mode: StorageMode;
+    /** The deprecated alias that was normalized to `cloud`, if any. */
+    deprecatedAlias: string | null;
+}
+/**
+ * Normalize a raw storage-mode string to the `local | cloud` runtime enum.
+ * Accepts deprecated aliases (`remote`, `hybrid`, `self_hosted`) and maps them
+ * to `cloud`. Throws on any other value.
+ */
+export declare function normalizeStorageMode(value: string): StorageModeNormalization;
+/** Upper-snake env token for an app name, e.g. `todos` -> `TODOS`. */
+export declare function envToken(name: string): string;
+export interface StorageEnvKeys {
+    /** `HASNA_<NAME>_STORAGE_MODE` then the optional `<NAME>_STORAGE_MODE` alias. */
+    modeKeys: string[];
+    /** `HASNA_<NAME>_DATABASE_URL` then the optional `<NAME>_DATABASE_URL` alias. */
+    databaseUrlKeys: string[];
+}
+/** Resolve the canonical env-key spec for an app's storage config. */
+export declare function storageEnvKeys(name: string): StorageEnvKeys;
+export interface StorageModeResolution {
+    mode: StorageMode;
+    /** Env key the mode came from, or `"default"`. */
+    source: string;
+    deprecatedAlias: string | null;
+    databaseUrlPresent: boolean;
+    /** Env key the database URL came from, or `null`. */
+    databaseUrlSource: string | null;
+    warning: string | null;
+}
+/**
+ * Resolve an app's storage mode from the environment per the contract env spec.
+ * Precedence: `HASNA_<NAME>_STORAGE_MODE`, then `<NAME>_STORAGE_MODE`, else
+ * `local`. Never reads secret values — only detects DATABASE_URL presence.
+ */
+export declare function resolveStorageMode(name: string, env?: Env): StorageModeResolution;
+/**
+ * Resolve the database URL value for an app, honoring the canonical then alias
+ * env keys. Returns `null` when unset. The caller is responsible for never
+ * logging the returned value.
+ */
+export declare function resolveDatabaseUrl(name: string, env?: Env): string | null;

package/dist/generated/storage-kit/pool.d.ts

@@ -0,0 +1,33 @@
+import type { Pool } from "pg";
+import { type TlsResolveOptions } from "./tls.js";
+import { type PoolQueryClient } from "./query.js";
+export interface CreatePgPoolOptions extends TlsResolveOptions {
+    connectionString: string;
+    /** Max clients in the pool. Defaults to pg's default (10). */
+    max?: number;
+    /** Idle client timeout (ms). */
+    idleTimeoutMillis?: number;
+    /** Connection acquisition timeout (ms). */
+    connectionTimeoutMillis?: number;
+    /** Application name reported to Postgres (shows in pg_stat_activity). */
+    applicationName?: string;
+}
+/** Build a `pg.Pool` with fleet-standard TLS handling. */
+export declare function createPgPool(options: CreatePgPoolOptions): Pool;
+export interface CreateCloudPoolFromEnvOptions extends TlsResolveOptions {
+    max?: number;
+    idleTimeoutMillis?: number;
+    connectionTimeoutMillis?: number;
+    applicationName?: string;
+}
+export interface CloudPoolFromEnv {
+    client: PoolQueryClient;
+    connectionSource: string;
+}
+/**
+ * Resolve mode + database URL from the environment and build a cloud pool.
+ *
+ * Throws when the resolved mode is not `cloud` (PURE REMOTE has no Postgres in
+ * `local` mode) or when the database URL is missing. Never logs the URL.
+ */
+export declare function createCloudPoolFromEnv(appName: string, options?: CreateCloudPoolFromEnvOptions): CloudPoolFromEnv;

package/dist/generated/storage-kit/query.d.ts

@@ -0,0 +1,35 @@
+import type { Pool, QueryResultRow } from "pg";
+export interface QueryResult<T extends QueryResultRow> {
+    rows: T[];
+    rowCount: number;
+}
+/**
+ * Minimal executor contract. `pg.Pool` and `pg.PoolClient` both satisfy the
+ * `query` method; the wrapper builds the rest on top so tests can substitute a
+ * lightweight shim without pulling in a live Postgres.
+ */
+export interface PgExecutor {
+    query<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<{
+        rows: T[];
+        rowCount: number | null;
+    }>;
+}
+export interface TypedQueryClient {
+    query<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<QueryResult<T>>;
+    many<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    /** First row or `null`. Restored here after open-knowledge dropped it. */
+    get<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<T | null>;
+    /** Exactly one row; throws if zero or more than one row is returned. */
+    one<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<T>;
+    execute(sql: string, params?: readonly unknown[]): Promise<void>;
+}
+/** Wrap any `PgExecutor` (a Pool, a PoolClient, or a test shim) with the typed vocabulary. */
+export declare function wrapExecutor(executor: PgExecutor): TypedQueryClient;
+export interface PoolQueryClient extends TypedQueryClient {
+    readonly pool: Pool;
+    /** Run a callback inside a `BEGIN`/`COMMIT` transaction on a dedicated client. */
+    transaction<T>(fn: (client: TypedQueryClient) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/** Build a `PoolQueryClient` around a live `pg.Pool`. */
+export declare function createQueryClient(pool: Pool): PoolQueryClient;