@k2b/cloud 0.6.0-rc.0

package/src/services/service-accounts.ts

@@ -0,0 +1,184 @@
+import { err, fail, ok, type Result } from "@k2b/stdlib";
+import { sql } from "bun";
+import { isUniqueViolation } from "./postgres";
+
+export type ServiceAccountKind = "user_delegated" | "resource_bound";
+export type ServiceAccountStatus = "active" | "disabled";
+
+export type ServiceAccount = {
+  id: string;
+  name: string;
+  kind: ServiceAccountKind;
+  status: ServiceAccountStatus;
+  delegatedUserId: string | null;
+  appId: string | null;
+  resourceType: string | null;
+  resourceId: string | null;
+  createdBy: string | null;
+  createdAt: string;
+};
+
+type DbServiceAccount = {
+  id: string;
+  name: string;
+  kind: ServiceAccountKind;
+  status: ServiceAccountStatus;
+  delegated_user_id: string | null;
+  app_id: string | null;
+  resource_type: string | null;
+  resource_id: string | null;
+  created_by: string | null;
+  created_at: Date;
+};
+
+const mapServiceAccount = (row: DbServiceAccount): ServiceAccount => ({
+  id: row.id,
+  name: row.name,
+  kind: row.kind,
+  status: row.status,
+  delegatedUserId: row.delegated_user_id,
+  appId: row.app_id,
+  resourceType: row.resource_type,
+  resourceId: row.resource_id,
+  createdBy: row.created_by,
+  createdAt: row.created_at.toISOString(),
+});
+
+const trimRequired = (value: string): string => value.trim();
+
+const isForeignKeyViolation = (error: unknown): boolean => (error as { code?: string } | null)?.code === "23503";
+const RESOURCE_BOUND_UNIQUE_CONSTRAINT = "uniq_service_accounts_resource_bound";
+
+export const getByResource = async (params: {
+  appId: string;
+  resourceType: string;
+  resourceId: string;
+}): Promise<ServiceAccount | null> => {
+  const [row] = await sql<DbServiceAccount[]>`
+    SELECT id, name, kind, status, delegated_user_id, app_id, resource_type, resource_id, created_by, created_at
+    FROM auth.service_accounts
+    WHERE kind = 'resource_bound'
+      AND app_id = ${params.appId}
+      AND resource_type = ${params.resourceType}
+      AND resource_id = ${params.resourceId}
+    ORDER BY created_at ASC
+    LIMIT 1
+  `;
+  return row ? mapServiceAccount(row) : null;
+};
+
+export const get = async (params: { id: string }): Promise<ServiceAccount | null> => {
+  const [row] = await sql<DbServiceAccount[]>`
+    SELECT id, name, kind, status, delegated_user_id, app_id, resource_type, resource_id, created_by, created_at
+    FROM auth.service_accounts
+    WHERE id = ${params.id}::uuid
+  `;
+  return row ? mapServiceAccount(row) : null;
+};
+
+export const createUserDelegated = async (params: {
+  name: string;
+  delegatedUserId: string;
+  createdBy?: string | null;
+}): Promise<Result<ServiceAccount>> => {
+  const name = trimRequired(params.name);
+  if (!name) return fail(err.badInput("Service account name is required"));
+
+  try {
+    const [row] = await sql<DbServiceAccount[]>`
+      INSERT INTO auth.service_accounts (name, kind, delegated_user_id, created_by)
+      VALUES (${name}, 'user_delegated', ${params.delegatedUserId}::uuid, ${params.createdBy ?? null}::uuid)
+      RETURNING id, name, kind, status, delegated_user_id, app_id, resource_type, resource_id, created_by, created_at
+    `;
+    return row ? ok(mapServiceAccount(row)) : fail(err.internal("Failed to create service account"));
+  } catch (error) {
+    if (isForeignKeyViolation(error)) return fail(err.notFound("Delegated user"));
+    throw error;
+  }
+};
+
+export const createResourceBound = async (params: {
+  name: string;
+  appId: string;
+  resourceType: string;
+  resourceId: string;
+  createdBy?: string | null;
+}): Promise<Result<ServiceAccount>> => {
+  const name = trimRequired(params.name);
+  const appId = trimRequired(params.appId);
+  const resourceType = trimRequired(params.resourceType);
+  const resourceId = trimRequired(params.resourceId);
+  if (!name) return fail(err.badInput("Service account name is required"));
+  if (!appId || !resourceType || !resourceId) return fail(err.badInput("Resource binding is required"));
+
+  try {
+    const [row] = await sql<DbServiceAccount[]>`
+      INSERT INTO auth.service_accounts (name, kind, app_id, resource_type, resource_id, created_by)
+      VALUES (${name}, 'resource_bound', ${appId}, ${resourceType}, ${resourceId}, ${params.createdBy ?? null}::uuid)
+      RETURNING id, name, kind, status, delegated_user_id, app_id, resource_type, resource_id, created_by, created_at
+    `;
+    return row ? ok(mapServiceAccount(row)) : fail(err.internal("Failed to create service account"));
+  } catch (error) {
+    if (isForeignKeyViolation(error)) return fail(err.notFound("Creator"));
+    if (isUniqueViolation(error, RESOURCE_BOUND_UNIQUE_CONSTRAINT)) return fail(err.conflict("Resource service account"));
+    throw error;
+  }
+};
+
+export const getOrCreateResourceBound = async (params: {
+  name: string;
+  appId: string;
+  resourceType: string;
+  resourceId: string;
+  createdBy?: string | null;
+}): Promise<Result<ServiceAccount>> => {
+  const existing = await getByResource(params);
+  if (existing) return ok(existing);
+
+  const created = await createResourceBound(params);
+  if (created.ok || created.error.code !== "CONFLICT") return created;
+
+  const raced = await getByResource(params);
+  return raced ? ok(raced) : fail(err.internal("Failed to load resource service account"));
+};
+
+export const setStatus = async (params: { id: string; status: ServiceAccountStatus }): Promise<Result<void>> => {
+  const result = await sql`
+    UPDATE auth.service_accounts
+    SET status = ${params.status}
+    WHERE id = ${params.id}::uuid
+  `;
+  if (result.count === 0) return fail(err.notFound("Service account"));
+  return ok();
+};
+
+export const delete_ = async (params: { id: string }): Promise<Result<void>> => {
+  const result = await sql`
+    DELETE FROM auth.service_accounts
+    WHERE id = ${params.id}::uuid
+  `;
+  if (result.count === 0) return fail(err.notFound("Service account"));
+  return ok();
+};
+
+export const deleteForResource = async (params: { appId: string; resourceType: string; resourceId: string }): Promise<number> => {
+  const result = await sql`
+    DELETE FROM auth.service_accounts
+    WHERE kind = 'resource_bound'
+      AND app_id = ${params.appId}
+      AND resource_type = ${params.resourceType}
+      AND resource_id = ${params.resourceId}
+  `;
+  return result.count;
+};
+
+export const serviceAccounts = {
+  get,
+  createUserDelegated,
+  createResourceBound,
+  getByResource,
+  getOrCreateResourceBound,
+  setStatus,
+  delete: delete_,
+  deleteForResource,
+};

package/src/services/session/index.ts

@@ -0,0 +1,236 @@
+import { sql } from "bun";
+import type { Context } from "hono";
+import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { HTTPException } from "hono/http-exception";
+import { env } from "../../config/env";
+import type { User } from "../../contracts/shared";
+import { isAccountCategoryAllowed } from "../account-category-policy";
+import { isAccountExpired } from "../account-model";
+import { IDENTITY_CLOCK_TOLERANCE_SECONDS, IDENTITY_ROLLOUT_MARGIN_MS } from "../identity/constants";
+import { invalidateIdentitySignerCache, prepareIdentitySigner } from "../identity/key-ring";
+import { getIdentityRuntimeConfig } from "../identity/runtime-config";
+import { type CloudSessionClaims, isSessionJwtCandidate, signSessionToken, verifySessionToken } from "../identity/session-token";
+import * as settings from "../settings";
+import { loadJwtSessionUser } from "./user";
+
+export type SessionData = {
+  userId: string;
+  sid: string;
+  authEpoch: number;
+  expiresAt: string;
+};
+
+export type AuthenticatedSession = { data: SessionData; user: User };
+
+const parseBearer = (header: string | undefined): string | null => {
+  if (!header) return null;
+  const match = header.match(/^Bearer\s+(\S+)$/i);
+  return match?.[1] ?? null;
+};
+
+const isCloudApiToken = (token: string | null): boolean => Boolean(token?.startsWith("cld_"));
+
+const verifyCredential = async (token: string): Promise<CloudSessionClaims | null> => {
+  if (!isSessionJwtCandidate(token)) return null;
+  return verifySessionToken(token);
+};
+
+const verificationByRequest = new WeakMap<Context, Map<string, Promise<CloudSessionClaims | null>>>();
+const authenticationByRequest = new WeakMap<Context, Map<string, Promise<AuthenticatedSession | null>>>();
+
+const requestCached = <T>(
+  cache: WeakMap<Context, Map<string, Promise<T>>>,
+  c: Context,
+  token: string,
+  load: () => Promise<T>,
+): Promise<T> => {
+  let requests = cache.get(c);
+  if (!requests) {
+    requests = new Map();
+    cache.set(c, requests);
+  }
+  const existing = requests.get(token);
+  if (existing) return existing;
+  const pending = load();
+  requests.set(token, pending);
+  return pending;
+};
+
+const verifyForRequest = (c: Context, token: string): Promise<CloudSessionClaims | null> =>
+  requestCached(verificationByRequest, c, token, () => verifyCredential(token));
+
+const authenticateVerified = async (credential: CloudSessionClaims): Promise<AuthenticatedSession | null> => {
+  const { groupsAdmin } = await getIdentityRuntimeConfig();
+  const user = await loadJwtSessionUser({
+    userId: credential.sub,
+    sid: credential.sid,
+    authEpoch: credential.auth_epoch,
+    groupsAdmin,
+  });
+  if (!user) return null;
+  if (!(await isAccountCategoryAllowed(user))) return null;
+  if (isAccountExpired(user.accountExpires)) {
+    await session.revokeAllForUser(user.id);
+    return null;
+  }
+  return {
+    user,
+    data: {
+      userId: user.id,
+      sid: credential.sid,
+      authEpoch: credential.auth_epoch,
+      expiresAt: new Date(credential.exp * 1_000).toISOString(),
+    },
+  };
+};
+
+const authenticateToken = async (token: string): Promise<AuthenticatedSession | null> => {
+  const credential = await verifyCredential(token);
+  return credential ? authenticateVerified(credential) : null;
+};
+
+const revokeToken = async (token: string, requestId?: string | null): Promise<void> => {
+  if (isSessionJwtCandidate(token)) {
+    const claims = await verifySessionToken(token);
+    if (!claims) return;
+    await sql`
+      UPDATE auth.session_families
+      SET revoked_at = COALESCE(revoked_at, now()),
+          revocation_reason = COALESCE(revocation_reason, 'logout'),
+          revoked_request_id = COALESCE(revoked_request_id, ${requestId?.slice(0, 64) ?? null})
+      WHERE sid = ${claims.sid}::uuid AND user_id = ${claims.sub}::uuid
+    `;
+    return;
+  }
+};
+
+const issueJwtSession = async (c: Context, userId: string, ttlSeconds: number, attempt = 0): Promise<string> => {
+  const issuedAt = new Date();
+  const expiresAt = new Date(issuedAt.getTime() + ttlSeconds * 1_000);
+  const sid = crypto.randomUUID();
+  const signer = await prepareIdentitySigner("session");
+  const requestId = c.req.header("x-request-id")?.slice(0, 64) ?? null;
+  const userAgent = c.req.header("user-agent")?.slice(0, 256) ?? null;
+
+  let authEpoch: number;
+  try {
+    authEpoch = await sql.begin(async (tx) => {
+      const [user] = await tx<Array<{ auth_epoch: string | number | bigint; provider: "local" | "ipa"; profile: "guest" | "user" }>>`
+        SELECT auth_epoch, provider, profile FROM auth.users WHERE id = ${userId}::uuid FOR UPDATE
+      `;
+      if (!user) throw new Error("Cannot create a session for an unknown user");
+      if (!(await isAccountCategoryAllowed(user, tx)))
+        throw new HTTPException(403, { message: "This account category is disabled. Contact an administrator." });
+      const epoch = Number(user.auth_epoch);
+      if (!Number.isSafeInteger(epoch) || epoch < 0) throw new Error("User auth_epoch is invalid");
+      const [activeKey] = await tx<Array<{ kid: string }>>`
+        UPDATE auth.signing_keys
+        SET verify_until = GREATEST(verify_until, ${new Date(
+          expiresAt.getTime() + IDENTITY_CLOCK_TOLERANCE_SECONDS * 1_000 + IDENTITY_ROLLOUT_MARGIN_MS,
+        )})
+        WHERE kid = ${signer.kid} AND purpose = 'session' AND state = 'active' AND sign_until > now()
+        RETURNING kid
+      `;
+      if (!activeKey) throw new Error("Prepared Cloud session signer is no longer active");
+      await tx`
+        INSERT INTO auth.session_families (
+          sid, user_id, auth_epoch, signing_kid, issued_at, expires_at, created_request_id, created_user_agent, legal_pending
+        ) VALUES (${sid}, ${userId}, ${epoch}, ${signer.kid}, ${issuedAt}, ${expiresAt}, ${requestId}, ${userAgent},
+          NOT EXISTS (SELECT 1 FROM auth.legal_acceptances WHERE user_id = ${userId}::uuid))
+      `;
+      await tx`UPDATE auth.users SET last_login_local = ${issuedAt} WHERE id = ${userId}::uuid`;
+      return epoch;
+    });
+  } catch (error) {
+    if (attempt === 0 && error instanceof Error && error.message === "Prepared Cloud session signer is no longer active") {
+      invalidateIdentitySignerCache("session", signer.kid);
+      return issueJwtSession(c, userId, ttlSeconds, 1);
+    }
+    throw error;
+  }
+
+  let token: string;
+  try {
+    token = (await signSessionToken({ userId, sid, authEpoch, issuedAt, expiresAt, signer })).token;
+  } catch (error) {
+    await sql`
+      UPDATE auth.session_families
+      SET revoked_at = now(), revocation_reason = 'issuance_failed'
+      WHERE sid = ${sid}::uuid AND revoked_at IS NULL
+    `;
+    throw error;
+  }
+
+  const [stillActive] = await sql<Array<{ active: boolean }>>`
+    SELECT EXISTS(
+      SELECT 1 FROM auth.signing_keys
+      WHERE kid = ${signer.kid} AND purpose = 'session' AND state = 'active'
+    ) AS active
+  `;
+  if (stillActive?.active) return token;
+
+  await sql`
+    UPDATE auth.session_families
+    SET revoked_at = now(), revocation_reason = 'signer_revoked_during_issuance'
+    WHERE sid = ${sid}::uuid AND revoked_at IS NULL
+  `;
+  invalidateIdentitySignerCache("session", signer.kid);
+  if (attempt === 0) return issueJwtSession(c, userId, ttlSeconds, 1);
+  throw new Error("Cloud session signer changed repeatedly during issuance");
+};
+
+export const session = {
+  getToken: (c: Context): string | null => {
+    const authorization = c.req.header("Authorization");
+    const bearer = parseBearer(authorization);
+    if (/^Bearer(?:\s|$)/i.test(authorization ?? "")) return isCloudApiToken(bearer) ? null : bearer;
+    return getCookie(c, "session_token") ?? null;
+  },
+
+  getBearerToken: (c: Context): string | null => parseBearer(c.req.header("Authorization")),
+
+  create: async (c: Context, userId: string): Promise<string> => {
+    const expiryHours = await settings.get<number>("user.session.expiry_hours");
+    if (!Number.isFinite(expiryHours) || expiryHours < 1) throw new Error("user.session.expiry_hours must be a positive number");
+    const ttlSeconds = Math.floor(expiryHours * 60 * 60);
+    const clientToken = await issueJwtSession(c, userId, ttlSeconds);
+
+    setCookie(c, "session_token", clientToken, {
+      httpOnly: true,
+      secure: !env.IS_DEVELOPMENT,
+      sameSite: "Lax",
+      maxAge: ttlSeconds,
+      path: "/",
+    });
+    return clientToken;
+  },
+
+  revoke: revokeToken,
+
+  delete: async (c: Context): Promise<void> => {
+    const token = session.getToken(c);
+    if (token) await revokeToken(token, c.req.header("x-request-id"));
+    deleteCookie(c, "session_token", { path: "/" });
+  },
+
+  revokeAllForUser: async (userId: string): Promise<void> => {
+    const [updated] = await sql<Array<{ id: string }>>`
+      UPDATE auth.users SET auth_epoch = auth_epoch + 1
+      WHERE id = ${userId}::uuid RETURNING id
+    `;
+    if (!updated) throw new Error("Cannot revoke sessions for an unknown user");
+  },
+
+  authenticate: authenticateToken,
+
+  authenticateRequest: (c: Context, token: string): Promise<AuthenticatedSession | null> =>
+    requestCached(authenticationByRequest, c, token, async () => {
+      const credential = await verifyForRequest(c, token);
+      return credential ? authenticateVerified(credential) : null;
+    }),
+
+  getRequestSubject: async (c: Context, token: string): Promise<string | null> => {
+    const credential = await verifyForRequest(c, token);
+    return credential?.sub ?? null;
+  },
+};

package/src/services/session/test-fixture.ts

@@ -0,0 +1,18 @@
+import { Hono } from "hono";
+import { sql } from "bun";
+import { session } from "./index";
+
+/** Integration fixture: run with an isolated Core authority and its public JWKS endpoint. */
+export const createTestSession = async (userId: string): Promise<string> => {
+  // Most session fixtures represent established users, not first-use onboarding.
+  await sql`INSERT INTO auth.legal_acceptances (user_id, session_id, document_version, documents)
+    VALUES (${userId}::uuid, ${crypto.randomUUID()}::uuid, 'test-fixture', '[]'::jsonb) ON CONFLICT DO NOTHING`;
+  const app = new Hono().post("/login", async (c) => c.json({ token: await session.create(c, userId) }));
+  const response = await app.request("/login", { method: "POST" });
+  if (response.status !== 200) throw new Error(`Session fixture login failed: ${response.status}`);
+  const body: unknown = await response.json();
+  if (!body || typeof body !== "object" || !("token" in body) || typeof body.token !== "string") {
+    throw new Error("Session fixture did not return a token");
+  }
+  return body.token;
+};

package/src/services/session/user.ts

@@ -0,0 +1,144 @@
+import { sql } from "bun";
+import type { User } from "../../contracts/shared";
+import { buildRoles } from "../accounts/authz";
+import { resolveProviderProfile } from "../accounts/base-user";
+import { managedGroupIdsSubquery, managedGroupsNamesSubquery } from "../accounts/group-sql";
+import { buildIpaUserData, emptyIpaUserData, userIpaDataColumns, userIpaDataJoin } from "../accounts/ipa-data";
+import { resolveAccountExpires } from "../accounts/model";
+import { toPgTextArray } from "../postgres";
+
+type DbRow = Record<string, unknown>;
+
+const pgArrayLiteralToStrings = (value: string): string[] => {
+  if (value === "{}") return [];
+  if (!value.startsWith("{") || !value.endsWith("}")) return [];
+  const items: string[] = [];
+  let item = "";
+  let quoted = false;
+  let escaped = false;
+  let wasQuoted = false;
+  for (const char of value.slice(1, -1)) {
+    if (escaped) {
+      item += char;
+      escaped = false;
+    } else if (char === "\\") {
+      escaped = true;
+    } else if (char === '"') {
+      quoted = !quoted;
+      wasQuoted = true;
+    } else if (char === "," && !quoted) {
+      if (wasQuoted || (item !== "" && item !== "NULL")) items.push(item);
+      item = "";
+      wasQuoted = false;
+    } else {
+      item += char;
+    }
+  }
+  if (wasQuoted || (item !== "" && item !== "NULL")) items.push(item);
+  return items;
+};
+
+const stringArray = (value: unknown): string[] => {
+  if (Array.isArray(value)) return value.filter((item): item is string => typeof item === "string");
+  if (typeof value === "string") return pgArrayLiteralToStrings(value);
+  return [];
+};
+
+export const buildProjectedUser = (row: DbRow): User => {
+  const { provider, profile } = resolveProviderProfile(row);
+  const mail = (row.mail as string | null | undefined) ?? null;
+  const displayName = (row.display_name as string | null | undefined) ?? "";
+  const memberofGroup = stringArray(row.member_groups);
+  const memberofGroupIds = stringArray(row.member_group_ids);
+  const manages = stringArray(row.manages);
+  const managesGroupIds = stringArray(row.manages_group_ids);
+  const common = {
+    id: row.id as string,
+    uid: row.uid as string,
+    roles: buildRoles({ provider, profile, memberofGroup, manages, admin: Boolean(row.effective_admin) }),
+    profile,
+    givenname: (row.given_name as string | null | undefined) ?? "",
+    sn: (row.sn as string | null | undefined) ?? "",
+    displayName: displayName || (profile === "guest" && mail ? mail : ""),
+    mail,
+    avatarHash: (row.avatar_hash as string | null | undefined) ?? null,
+    accountExpires: resolveAccountExpires(row)?.toISOString() ?? null,
+    lastLoginLocal: row.last_login_local ? new Date(row.last_login_local as Date | string).toISOString() : null,
+    memberofGroup,
+    memberofGroupIds,
+    manages,
+    managesGroupIds,
+  };
+  return provider === "ipa"
+    ? { ...common, provider: "ipa", ipa: buildIpaUserData(row) ?? emptyIpaUserData() }
+    : { ...common, provider: "local", ipa: null };
+};
+
+export const userProjectionSql = (groupsAdmin: string[]) => sql`
+  u.*,
+  ${userIpaDataColumns},
+  CASE
+    WHEN u.provider = 'local' THEN u.admin
+    ELSE EXISTS(
+      SELECT 1 FROM auth.ipa_user_effective_groups eg
+      WHERE eg.user_id = u.id
+        AND eg.group_name = ANY(${toPgTextArray(groupsAdmin)}::text[])
+    )
+  END AS effective_admin,
+  COALESCE(ARRAY(
+    SELECT g.name
+    FROM auth.user_groups_v2 ug
+    JOIN auth.groups g ON g.id = ug.group_id
+    WHERE ug.user_id = u.id
+    ORDER BY g.name
+  ), '{}') AS member_groups,
+  COALESCE(ARRAY(
+    SELECT ug.group_id
+    FROM auth.user_groups_v2 ug
+    JOIN auth.groups g ON g.id = ug.group_id
+    WHERE ug.user_id = u.id
+    ORDER BY g.name
+  ), '{}') AS member_group_ids,
+  COALESCE(ARRAY(${managedGroupsNamesSubquery(sql`u.id`)}), '{}') AS manages,
+  COALESCE(ARRAY(${managedGroupIdsSubquery(sql`u.id`)}), '{}') AS manages_group_ids
+`;
+
+export const loadJwtSessionUser = async (
+  params: {
+    userId: string;
+    sid: string;
+    authEpoch: number;
+    groupsAdmin: string[];
+    /** Core's consent screen only: still validates family, epoch and expiry. */
+    allowPendingLegalConsent?: boolean;
+  },
+  query: typeof sql = sql,
+): Promise<User | null> => {
+  const rows = await query<DbRow[]>`
+    SELECT ${userProjectionSql(params.groupsAdmin)}
+    FROM auth.session_families sf
+    JOIN auth.users u ON u.id = sf.user_id
+    JOIN auth.signing_keys sk ON sk.kid = sf.signing_kid AND sk.state <> 'revoked'
+    ${userIpaDataJoin}
+    WHERE sf.sid = ${params.sid}::uuid
+      AND sf.user_id = ${params.userId}::uuid
+      AND sf.auth_epoch = ${params.authEpoch}
+      AND u.auth_epoch = ${params.authEpoch}
+      AND sf.revoked_at IS NULL
+      AND sf.expires_at > now()
+      AND (${params.allowPendingLegalConsent === true} OR NOT sf.legal_pending OR EXISTS (
+        SELECT 1 FROM auth.legal_acceptances la WHERE la.user_id = u.id
+      ))
+  `;
+  return rows[0] ? buildProjectedUser(rows[0]) : null;
+};
+
+export const loadCurrentUser = async (params: { userId: string; groupsAdmin: string[] }, query: typeof sql = sql): Promise<User | null> => {
+  const rows = await query<DbRow[]>`
+    SELECT ${userProjectionSql(params.groupsAdmin)}
+    FROM auth.users u
+    ${userIpaDataJoin}
+    WHERE u.id = ${params.userId}::uuid
+  `;
+  return rows[0] ? buildProjectedUser(rows[0]) : null;
+};

package/src/services/settings/api.ts

@@ -0,0 +1,61 @@
+/**
+ * Typed async settings API.
+ *
+ * Two surfaces are exposed:
+ *
+ *  1. `app.settings` — created by `defineApp`, typed against that app's own
+ *     declared settings (plus any core settings since core's snapshot is
+ *     loaded into every container). Available on the AppDefinition return value.
+ *
+ *  2. `coreSettings` — for cloud-lib internal services that don't have an
+ *     `app` reference (e.g. `services/notifications/email.ts`,
+ *     `services/weather/forecast.ts`, OpenAPI middleware, cron callbacks).
+ *     Loosely typed (caller provides the value type via the `T` generic).
+ *
+ * Backend: cache-aside via `store.ts` (Redis 5min TTL + DB fallback). All
+ * functions are async — sync render-time access uses the per-request snapshot
+ * exposed via `c.get("settings")`.
+ */
+
+import type { AppSettingsMap, KindToType } from "../../contracts/settings-types";
+import { deleteKey, readKey, writeKey } from "./store";
+
+/**
+ * Per-app typed settings API. Keys constrained to those declared in the
+ * app's `defineApp({ settings: ... })` block.
+ */
+export interface SettingsAPI<F extends Record<string, unknown>> {
+  get<K extends keyof F & string>(key: K): Promise<F[K]>;
+  set<K extends keyof F & string>(key: K, value: F[K]): Promise<void>;
+  remove<K extends keyof F & string>(key: K): Promise<void>;
+}
+
+/**
+ * Build a typed SettingsAPI for a given AppSettingsMap.
+ *
+ * The runtime is identical for every app (delegates to store.ts); the typing
+ * is purely a TS construct that constrains keys/values to what was declared.
+ */
+export const createSettingsAPI = <S extends AppSettingsMap>(): SettingsAPI<{
+  [K in keyof S]: KindToType<S[K]["kind"]>;
+}> => ({
+  get: async (key) => readKey(key) as never,
+  set: async (key, value) => writeKey(key, value),
+  remove: async (key) => deleteKey(key),
+});
+
+/**
+ * cloud-lib internal services and other apps use `coreSettings` for any
+ * setting access outside of a per-request context. Loose-typed (the caller
+ * specifies the expected value type via the `T` generic) — apps that need
+ * tight typing for their OWN settings use `app.settings.get/set` instead.
+ *
+ * Usage:
+ *   await coreSettings.get<string>("app.name");          // string
+ *   await coreSettings.set("freeipa.enable", true);       // value type free
+ */
+export const coreSettings = {
+  get: <T = unknown>(key: string): Promise<T> => readKey(key) as Promise<T>,
+  set: (key: string, value: unknown): Promise<void> => writeKey(key, value),
+  remove: (key: string): Promise<void> => deleteKey(key),
+};