@k2b/cloud 0.47.0 → 0.49.0

package/src/services/identity/invocation-token.ts

@@ -507,6 +507,26 @@ const AppQueryClaimsSchema = z
   .strict()
   .refine((claims) => claims.nbf === claims.iat && claims.exp - claims.iat === CLOUD_INVOCATION_TOKEN_TTL_SECONDS);
 
+const AppCapabilityClaimsSchema = z
+  .object({
+    iss: z.string().url(),
+    aud: z.string().regex(/^app:[a-z][a-z0-9-]{0,79}$/),
+    token_use: z.literal("app_capability"),
+    sub: AppIdSchema,
+    key_id: z.uuid(),
+    permission: z.string().min(1).max(100),
+    op: OperationSchema.refine((value) => value.startsWith("capability.query:") || value.startsWith("capability.action:")),
+    schema_hash: z.string().regex(/^[a-f0-9]{64}$/),
+    input_hash: z.string().regex(/^[a-f0-9]{64}$/),
+    request_id: BoundedIdentifierSchema,
+    jti: z.uuid(),
+    iat: z.number().int(),
+    nbf: z.number().int(),
+    exp: z.number().int(),
+  })
+  .strict()
+  .refine((claims) => claims.nbf === claims.iat && claims.exp - claims.iat === CLOUD_INVOCATION_TOKEN_TTL_SECONDS);
+
 export const signAppQueryInvocation = async (input: {
   workload: import("./workload-auth").AuthenticatedWorkload;
   targetAppId: string;
@@ -595,3 +615,95 @@ export const verifyAppQueryInvocation = async (
     throw error;
   }
 };
+
+export const signAppCapabilityInvocation = async (input: {
+  app: { appId: string; keyId: string };
+  kind: "query" | "action";
+  permission: string;
+  targetAppId: string;
+  capabilityId: string;
+  schemaHash: string;
+  input: unknown;
+  requestId: string;
+  signer: PreparedIdentitySigner & { issuer: string };
+}) => {
+  const now = Math.floor(Date.now() / 1000);
+  if (input.signer.signUntil.getTime() < (now + CLOUD_INVOCATION_TOKEN_TTL_SECONDS) * 1000)
+    throw new Error("Signing key expires before the app capability invocation");
+  const claims = AppCapabilityClaimsSchema.parse({
+    iss: input.signer.issuer,
+    aud: `app:${input.targetAppId}`,
+    token_use: "app_capability",
+    sub: input.app.appId,
+    key_id: input.app.keyId,
+    permission: input.permission,
+    op: `capability.${input.kind}:${input.capabilityId}`,
+    schema_hash: input.schemaHash,
+    input_hash: appEventPayloadHash(input.input),
+    request_id: input.requestId,
+    jti: crypto.randomUUID(),
+    iat: now,
+    nbf: now,
+    exp: now + CLOUD_INVOCATION_TOKEN_TTL_SECONDS,
+  });
+  const token = await new SignJWT(claims)
+    .setProtectedHeader({ alg: CLOUD_IDENTITY_ALGORITHM, typ: CLOUD_INVOCATION_TOKEN_TYPE, kid: input.signer.kid })
+    .sign(input.signer.key);
+  if (Buffer.byteLength(token) > IDENTITY_MAX_COMPACT_TOKEN_BYTES) throw new Error("App capability token exceeds its byte budget");
+  return { token, claims };
+};
+
+export const verifyAppCapabilityInvocation = async (
+  token: string,
+  expected: { appId: string; kind: "query" | "action"; capabilityId: string; schemaHash: string; input: unknown; permission: string },
+  options: { issuer?: string; key?: JWTVerifyGetKey; now?: Date } = {},
+) => {
+  if (Buffer.byteLength(token) > IDENTITY_MAX_COMPACT_TOKEN_BYTES) return null;
+  try {
+    assertProtectedHeader(decodeProtectedHeader(token));
+  } catch {
+    return null;
+  }
+  // Configuration and key-fetch failures must remain retryable, rather than look like invalid tokens.
+  const runtime = options.issuer && options.key ? null : await getIdentityRuntimeConfig();
+  try {
+    const issuer = options.issuer ?? runtime!.issuer;
+    const state = options.key ? null : remoteSet(runtime!.invocationJwksUrl);
+    const key = options.key ?? state!.key;
+    const verified = await verifyWithKeyRefresh(
+      (candidate) =>
+        jwtVerify(token, candidate, {
+          algorithms: [CLOUD_IDENTITY_ALGORITHM],
+          issuer,
+          audience: `app:${expected.appId}`,
+          typ: CLOUD_INVOCATION_TOKEN_TYPE,
+          clockTolerance: INVOCATION_CLOCK_TOLERANCE_SECONDS,
+          currentDate: options.now,
+        }),
+      key,
+      state ? { url: runtime!.invocationJwksUrl, state } : null,
+    );
+    const claims = AppCapabilityClaimsSchema.parse(verified.payload);
+    if (
+      claims.permission !== expected.permission ||
+      claims.op !== `capability.${expected.kind}:${expected.capabilityId}` ||
+      claims.schema_hash !== expected.schemaHash ||
+      claims.input_hash !== appEventPayloadHash(expected.input)
+    )
+      return null;
+    return claims;
+  } catch (error) {
+    if (
+      error instanceof z.ZodError ||
+      error instanceof errors.JWTExpired ||
+      error instanceof errors.JWTClaimValidationFailed ||
+      error instanceof errors.JWTInvalid ||
+      error instanceof errors.JWSInvalid ||
+      error instanceof errors.JWSSignatureVerificationFailed ||
+      error instanceof errors.JWKSNoMatchingKey ||
+      error instanceof errors.JOSENotSupported
+    )
+      return null;
+    throw error;
+  }
+};

package/src/services/identity/key-ring.ts

@@ -1,6 +1,6 @@
 import { crypto } from "@k2b/stdlib";
-import { sql } from "bun";
 import { CompactSign, compactVerify, exportJWK, generateKeyPair, importJWK, type JWK } from "jose";
+import { sql } from "../../runtime/clients";
 import { logger } from "../logging";
 import {
   CLOUD_IDENTITY_ALGORITHM,
@@ -449,7 +449,7 @@ export const initializeIdentityAuthority = async (): Promise<void> => {
   if (keys.previous) await rewrapIdentitySigningKeys();
 };
 
-export const listIdentityJwks = async (purpose: "session" | "invocation"): Promise<{ keys: JWK[]; etag: string }> => {
+export const listIdentityJwks = async (purpose: SigningKeyPurpose): Promise<{ keys: JWK[]; etag: string }> => {
   const rows = await sql<Array<{ public_jwk: JWK | string }>>`
         SELECT public_jwk
         FROM auth.signing_keys

package/src/services/identity/resource-readers.ts

@@ -1,7 +1,7 @@
-import { sql } from "bun";
 import { z } from "zod";
 import { type ResourcePrincipal, ResourcePrincipalSchema } from "../../contracts/capabilities";
 import type { AccessSubject } from "../../contracts/shared";
+import { sql } from "../../runtime/clients";
 import { decodeAccountCategoryEnabled } from "../account-category-policy";
 import { toPgUuidArray } from "../postgres";
 import type { ServiceAccount } from "../service-accounts";

package/src/services/identity/routes.ts

@@ -1,12 +1,17 @@
 import { type Context, Hono } from "hono";
-import { CLOUD_INVOCATION_JWKS_PATH, CLOUD_SESSION_JWKS_PATH, IDENTITY_JWKS_MAX_AGE_SECONDS } from "./constants";
+import {
+  CLOUD_INTERNAL_OAUTH_JWKS_PATH,
+  CLOUD_INVOCATION_JWKS_PATH,
+  CLOUD_SESSION_JWKS_PATH,
+  IDENTITY_JWKS_MAX_AGE_SECONDS,
+} from "./constants";
 import { listIdentityJwks } from "./key-ring";
 
 // If-None-Match uses weak comparison, including lists and the wildcard.
 const matchesEtag = (header: string | undefined, etag: string): boolean =>
   header?.trim() === "*" || (header?.match(/(?:W\/)?"[^"]*"/g) ?? []).some((tag) => tag.replace(/^W\//, "") === etag.replace(/^W\//, ""));
 
-const serveJwks = (purpose: "session" | "invocation") => async (c: Context) => {
+const serveJwks = (purpose: "session" | "invocation" | "oauth") => async (c: Context) => {
   const jwks = await listIdentityJwks(purpose);
   if (matchesEtag(c.req.header("if-none-match"), jwks.etag)) {
     c.header("ETag", jwks.etag);
@@ -19,4 +24,7 @@ const serveJwks = (purpose: "session" | "invocation") => async (c: Context) => {
 };
 
 export const createIdentityPublicRoutes = (): Hono =>
-  new Hono().get(CLOUD_SESSION_JWKS_PATH, serveJwks("session")).get(CLOUD_INVOCATION_JWKS_PATH, serveJwks("invocation"));
+  new Hono()
+    .get(CLOUD_SESSION_JWKS_PATH, serveJwks("session"))
+    .get(CLOUD_INVOCATION_JWKS_PATH, serveJwks("invocation"))
+    .get(CLOUD_INTERNAL_OAUTH_JWKS_PATH, serveJwks("oauth"));

package/src/services/identity/runtime-config.ts

@@ -4,7 +4,13 @@ import { publicCloudOrigin } from "../../shared/app-url";
 import { get as getSetting } from "../settings";
 import { decryptValue } from "../settings/crypto";
 import { SETTINGS_MAP, validateSettingValue } from "../settings/defaults";
-import { CLOUD_INVOCATION_JWKS_PATH, CLOUD_OAUTH_JWKS_PATH, CLOUD_SESSION_JWKS_PATH, IDENTITY_REFRESH_TIMEOUT_MS } from "./constants";
+import {
+  CLOUD_INTERNAL_OAUTH_JWKS_PATH,
+  CLOUD_INVOCATION_JWKS_PATH,
+  CLOUD_OAUTH_JWKS_PATH,
+  CLOUD_SESSION_JWKS_PATH,
+  IDENTITY_REFRESH_TIMEOUT_MS,
+} from "./constants";
 
 const RUNTIME_CONFIG_TTL_MS = 60_000;
 
@@ -75,8 +81,13 @@ export const resolveInvocationJwksUrl = (
   transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN ?? env.CLOUD_CORE_INTERNAL_ORIGIN,
 ): URL => resolveCoreJwksUrl(issuer, CLOUD_INVOCATION_JWKS_PATH, transportOrigin);
 
-export const resolveOAuthJwksUrl = (issuer: string, transportOrigin = env.CLOUD_OAUTH_JWKS_ORIGIN): URL => {
-  if (!transportOrigin) return new URL(CLOUD_OAUTH_JWKS_PATH, issuer);
+export const resolveOAuthJwksUrl = (
+  issuer: string,
+  transportOrigin = env.CLOUD_OAUTH_JWKS_ORIGIN,
+  coreOrigin = env.CLOUD_CORE_INTERNAL_ORIGIN,
+): URL => {
+  if (!transportOrigin)
+    return coreOrigin ? resolveCoreJwksUrl(issuer, CLOUD_INTERNAL_OAUTH_JWKS_PATH, coreOrigin) : new URL(CLOUD_OAUTH_JWKS_PATH, issuer);
 
   const url = new URL(CLOUD_OAUTH_JWKS_PATH, transportOrigin);
   if (url.protocol !== "http:" && url.protocol !== "https:") {

package/src/services/identity/workload-auth.ts

@@ -9,6 +9,8 @@ export type AuthenticatedWorkload = {
   serviceAccountId: string;
   credentialId: string;
   scope: WorkloadScope;
+  /** Present only for a verified signed app request, never a legacy token. */
+  keyId?: string;
 };
 
 type WorkloadCredentialAuthenticator = Pick<typeof serviceAccountCredentials, "isApiToken" | "authenticateApiToken">;

package/src/services/identity/workload-runtime.ts

@@ -1,6 +1,5 @@
 /** Core-only workload issuer. This module never reads identity signing keys, OAuth secrets, or sessions. */
 import type { NatsConnection } from "@nats-io/transport-node";
-import { sql } from "bun";
 import { getProcessNats } from "../../_internal/process-sync";
 import { APP_REGISTRY_TTL_MS, appInstancePrefix, appInstanceRegistry } from "../../_internal/registry";
 import {
@@ -12,7 +11,8 @@ import {
   type WorkloadResponse,
   workloadSubject,
 } from "../../_internal/workload-protocol";
-import { env } from "../../config/env";
+import { sql } from "../../runtime/clients";
+import { connections } from "../../runtime/connections";
 import { audit } from "../audit";
 import { logger } from "../logging";
 import { serviceAccountCredentials } from "../service-account-credentials";
@@ -204,7 +204,7 @@ export const startAppWorkloadBroker = async (
   let stopped = false;
   let maintenance: Promise<void> | undefined;
   let timer: Timer | undefined;
-  const subscription = connection.subscribe(workloadSubject(options.namespace ?? env.SYNC_NAMESPACE), {
+  const subscription = connection.subscribe(workloadSubject(options.namespace ?? connections().nats.namespace), {
     queue: "core-workload-v1",
     callback: (error, message) => {
       if (error || !message.reply) return;

package/src/services/index.ts

@@ -253,6 +253,7 @@ export type { NetworkLookup, PublicNetworkAddress } from "./network-security";
 
 export { geoip } from "./geoip";
 export { appDetails } from "./app-details";
+export { appAdminFacts, type AppAdminFacts } from "./app-admin-facts";
 export {
   knownBrowsers,
   KNOWN_BROWSER_LIMITS,
@@ -294,3 +295,6 @@ export type {
   ObjectListOptions,
   ObjectListResult,
 } from "./object-store";
+
+export { links } from "./links";
+export type { CreateLinkInput, CreatedLink, RedeemedLink, LinkOptions, PeekedLink, PeekLinkResult, RedeemLinkResult } from "./links";

package/src/services/ipa/groups.ts

@@ -1,5 +1,5 @@
-import { sql } from "bun";
 import type { BaseGroup, GroupMember, MutationResult } from "../../contracts/shared";
+import { sql } from "../../runtime/clients";
 import { freeipa } from "../../server/services";
 import { toPgUuidArray } from "../postgres";
 import { ensureFreeIpaMutationAvailable, getIpaUrl } from "./guard";

package/src/services/ipa/profile.ts

@@ -5,8 +5,8 @@
  * Local group mutations keep that projection as source of truth; the local
  * display mirror is only a bootstrap fallback before the first full sync.
  */
+import { sql } from "../../runtime/clients";
 
-import { sql } from "bun";
 import { calculateIpaProfileFromGroupNames } from "../account-model";
 import { getFreeIpaConfig } from "../freeipa-config";
 

package/src/services/ipa/search.ts

@@ -1,5 +1,5 @@
-import { sql } from "bun";
 import type { BaseGroup, BaseUser, UserProfile, UserProvider } from "../../contracts/shared";
+import { sql } from "../../runtime/clients";
 import { freeipa } from "../../server/services";
 import { buildRoles } from "../account-model";
 import { getFreeIpaConfig } from "../freeipa-config";

package/src/services/ipa/sync.ts

@@ -1,5 +1,5 @@
-import { sql } from "bun";
 import { coreUserEventPublisher } from "../../events/core-user-created";
+import { sql } from "../../runtime/clients";
 import { freeipa } from "../../server/services";
 import { writeDeletedAccountAudit } from "../account-lifecycle/audit";
 import { calculateIpaProfileFromGroupNames, parseIpaAccountTransitionPolicy, parseIpaMatchMode } from "../account-model";

package/src/services/ipa/users.ts

@@ -1,7 +1,7 @@
 import { password } from "@k2b/stdlib";
-import { sql } from "bun";
 import type { MutationResult, UserProfile } from "../../contracts/shared";
 import { coreUserEventPublisher } from "../../events/core-user-created";
+import { sql } from "../../runtime/clients";
 import { freeipa } from "../../server/services";
 import { writeDeletedAccountAudit } from "../account-lifecycle/audit";
 import { resolveProviderProfile } from "../accounts/base-user";

package/src/services/known-browsers.ts

@@ -1,9 +1,10 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import type { Context } from "hono";
 import { getCookie, setCookie } from "hono/cookie";
 import { z } from "zod";
 import { env } from "../config/env";
 import { APP_LOGIN_CONTEXT_BROWSERS, APP_LOGIN_CONTEXT_OSES } from "../contracts/app-approval";
+import { sql } from "../runtime/clients";
 import { type BrowserCode, type OsCode, truncateUtf8 } from "../server/request-context";
 import { logger } from "./logging";
 

package/src/services/legal-consent.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { sql } from "bun";
 import type { Context } from "hono";
 import { HTTPException } from "hono/http-exception";
+import { sql } from "../runtime/clients";
 import { isAccountCategoryAllowed } from "./account-category-policy";
 import { isAccountExpired } from "./account-model";
 import { verifySessionToken } from "./identity";

package/src/services/links/index.ts

@@ -0,0 +1,16 @@
+import { getProcessApplicationPackage } from "../../_internal/process-identity";
+import { sql } from "../../runtime/clients";
+import { type CreateLinkInput, createLinksStore, type LinkOptions } from "./store";
+
+const store = () => {
+  const packageName = getProcessApplicationPackage();
+  if (!packageName) throw new Error("Start the application before using one-time links");
+  return createLinksStore(sql, packageName);
+};
+
+export const links = {
+  create: (input: CreateLinkInput, options?: LinkOptions) => store().create(input, options),
+  peek: (token: string, input: { purpose: string }, options?: LinkOptions) => store().peek(token, input, options),
+  redeem: (token: string, input: { purpose: string }, options?: LinkOptions) => store().redeem(token, input, options),
+};
+export type { CreatedLink, CreateLinkInput, LinkOptions, PeekedLink, PeekLinkResult, RedeemedLink, RedeemLinkResult } from "./store";

package/src/services/links/runtime.ts

@@ -0,0 +1,44 @@
+import { lazySync } from "../../_internal/process-sync";
+import { sql } from "../../runtime/clients";
+import { logger } from "../logging";
+import { cleanupLinksBatch, LINK_CLEANUP_BATCH, setupLinks } from "./store";
+
+// All apps compete for one platform schedule, including replicas and apps sharing a package.
+const scheduler = lazySync((sync) =>
+  sync.scheduler({
+    id: "cloud-links-retention",
+    owner: "platform",
+    delivery: { maxAttempts: 2, backoffMs: [30_000], ackWaitMs: 60_000 },
+  }),
+);
+
+/** Provision before app setup and readiness, then drain this worker before NATS during shutdown. */
+export const startLinksRuntime = async (): Promise<() => Promise<void>> => {
+  await setupLinks(sql);
+  const stopping = new AbortController();
+  await scheduler().create({
+    id: "retention",
+    cron: "0 * * * *",
+    timezone: "UTC",
+    misfire: "latest",
+    meta: { family: "links", label: "One-time link cleanup" },
+    process: async ({ signal, heartbeat }) => {
+      const runSignal = AbortSignal.any([signal, stopping.signal]);
+      const deadline = performance.now() + 5 * 60_000;
+      let deleted = 0;
+      while (!runSignal.aborted && performance.now() < deadline) {
+        const count = await cleanupLinksBatch(sql);
+        deleted += count;
+        if (count < LINK_CLEANUP_BATCH) break;
+        await heartbeat();
+      }
+      if (deleted > 0) logger("links:cleanup").info("Removed old one-time links", { deleted });
+    },
+  });
+  const worker = await scheduler().process({ concurrency: 1 });
+  return async () => {
+    stopping.abort();
+    worker.stop();
+    await worker.drain({ timeoutMs: 30_000 });
+  };
+};

package/src/services/links/store.ts

@@ -0,0 +1,105 @@
+import { createHash, randomBytes } from "node:crypto";
+import type { SQL, TransactionSQL } from "bun";
+import { isPurposeName, validatePurposeName } from "../../_internal/purpose-name";
+import { ensureSchema } from "../postgres";
+
+export type CreateLinkInput = { purpose: string; subject: string; ttl: number };
+export type CreatedLink = { token: string; expiresAt: Date };
+export type RedeemedLink = { subject: string; createdAt: Date };
+export type PeekedLink = RedeemedLink & { expiresAt: Date };
+export type LinkOptions = { tx?: TransactionSQL };
+type LinkResult<T> = { ok: true; data: T } | { ok: false; error: { code: "LINK_INVALID" } };
+export type RedeemLinkResult = LinkResult<RedeemedLink>;
+export type PeekLinkResult = LinkResult<PeekedLink>;
+
+const TOKEN = /^cl_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
+// Match the existing outgoing-mail retention batch budget.
+export const LINK_CLEANUP_BATCH = 1000;
+const hashToken = (token: string): string => createHash("sha256").update(token).digest("hex");
+
+const linkCandidate = (token: string, purpose: string) => {
+  const value = typeof token === "string" ? token : "";
+  const digest = hashToken(value);
+  const validPurpose = isPurposeName(purpose);
+  return { digest, purpose: validPurpose ? purpose : "", valid: TOKEN.test(value) && validPurpose };
+};
+
+export const validateCreateLink = (input: CreateLinkInput): void => {
+  validatePurposeName(input.purpose);
+  if (typeof input.subject !== "string" || Buffer.byteLength(input.subject, "utf8") > 1024) {
+    throw new TypeError("Link subject must be a string of at most 1024 UTF-8 bytes");
+  }
+  if (!Number.isFinite(input.ttl) || input.ttl < 60 || input.ttl > 30 * 24 * 60 * 60) {
+    throw new RangeError("Link ttl must be seconds from 60 to 2592000 (30 days)");
+  }
+};
+
+/** One reserved platform table in the same database as the application's domain transactions. */
+export const setupLinks = async (db: SQL): Promise<void> => {
+  await db.begin(async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(hashtext('cloud.links'))`;
+    await ensureSchema(tx, "platform");
+    const [existing] = await tx<{ table_exists: boolean; index_exists: boolean }[]>`
+      SELECT to_regclass('platform._cloud_links') IS NOT NULL AS table_exists,
+        to_regclass('platform._cloud_links_retention') IS NOT NULL AS index_exists`;
+    if (!existing?.table_exists)
+      await tx`CREATE TABLE IF NOT EXISTS platform._cloud_links (
+      package text NOT NULL, token_hash text NOT NULL, purpose text NOT NULL, subject bytea NOT NULL,
+      created_at timestamptz NOT NULL, expires_at timestamptz NOT NULL, used_at timestamptz,
+      PRIMARY KEY (package, token_hash)
+    )`.simple();
+    // Even IF NOT EXISTS takes a ShareLock; skip index DDL on ordinary app restarts.
+    if (!existing?.index_exists)
+      await tx`CREATE INDEX IF NOT EXISTS _cloud_links_retention ON platform._cloud_links (LEAST(expires_at, used_at))`.simple();
+  });
+};
+
+export const createLinksStore = (db: SQL, packageName: string) => ({
+  create: async (input: CreateLinkInput, options: LinkOptions = {}): Promise<CreatedLink> => {
+    validateCreateLink(input);
+    const token = `cl_${randomBytes(32).toString("base64url")}`;
+    const [row] = await (options.tx ?? db)<{ expires_at: Date }[]>`
+      INSERT INTO platform._cloud_links (package, token_hash, purpose, subject, created_at, expires_at)
+      VALUES (${packageName}, ${hashToken(token)}, ${input.purpose}, ${Buffer.from(input.subject, "utf8")},
+        statement_timestamp(), statement_timestamp() + ${input.ttl} * interval '1 second')
+      RETURNING expires_at`;
+    if (!row) throw new Error("One-time link insert returned no expiry");
+    return { token, expiresAt: row.expires_at };
+  },
+  peek: async (token: string, input: { purpose: string }, options: LinkOptions = {}): Promise<PeekLinkResult> => {
+    const candidate = linkCandidate(token, input.purpose);
+    const [row] = await (options.tx ?? db)<{ subject: Uint8Array; created_at: Date; expires_at: Date }[]>`
+      SELECT subject, created_at, expires_at FROM platform._cloud_links
+      WHERE package = ${packageName} AND token_hash = ${candidate.digest} AND purpose = ${candidate.purpose}
+        AND ${candidate.valid}::boolean AND used_at IS NULL AND expires_at > clock_timestamp()`;
+    return row
+      ? { ok: true, data: { subject: Buffer.from(row.subject).toString("utf8"), createdAt: row.created_at, expiresAt: row.expires_at } }
+      : { ok: false, error: { code: "LINK_INVALID" } };
+  },
+  redeem: async (token: string, input: { purpose: string }, options: LinkOptions = {}): Promise<RedeemLinkResult> => {
+    // Every candidate is hashed and reaches one indexed UPDATE, including malformed credentials.
+    const candidate = linkCandidate(token, input.purpose);
+    const [row] = await (options.tx ?? db)<{ subject: Uint8Array; created_at: Date }[]>`
+      UPDATE platform._cloud_links SET used_at = clock_timestamp()
+      WHERE package = ${packageName} AND token_hash = ${candidate.digest} AND purpose = ${candidate.purpose}
+        AND ${candidate.valid}::boolean AND used_at IS NULL AND expires_at > clock_timestamp()
+      RETURNING subject, created_at`;
+    return row
+      ? { ok: true, data: { subject: Buffer.from(row.subject).toString("utf8"), createdAt: row.created_at } }
+      : { ok: false, error: { code: "LINK_INVALID" } };
+  },
+});
+
+/** Platform maintenance spans packages; the application facade never exposes this operation. */
+export const cleanupLinksBatch = async (db: SQL): Promise<number> =>
+  db.begin(async (tx) => {
+    await tx`SET LOCAL statement_timeout = '10s'`;
+    const rows = await tx<{ token_hash: string }[]>`
+      WITH expired AS (
+        SELECT package, token_hash FROM platform._cloud_links
+        WHERE LEAST(expires_at, used_at) < statement_timestamp() - interval '24 hours'
+        ORDER BY LEAST(expires_at, used_at) LIMIT ${LINK_CLEANUP_BATCH} FOR UPDATE SKIP LOCKED
+      ) DELETE FROM platform._cloud_links link USING expired
+        WHERE link.package = expired.package AND link.token_hash = expired.token_hash RETURNING link.token_hash`;
+    return rows.length;
+  });

package/src/services/logging/index.ts

@@ -1,8 +1,8 @@
-import { sql } from "bun";
 import type { PaginationParams } from "../../contracts/shared";
+import { sql } from "../../runtime/clients";
 import { escapeLikePattern, parsePgJsonRecord, toPgTextArray } from "../postgres";
 import { registerSettings } from "../settings/defaults";
-import { redactMetadata } from "./redaction";
+import { redactLinkTokens, redactMetadata } from "./redaction";
 import { observeSyncEvent, TRACE_STUCK_AFTER_MS, trace } from "./trace";
 import { readWebVitals } from "./web-vitals";
 
@@ -120,19 +120,24 @@ const mapRow = (row: DbLogRow): LogEntry => ({
 /** Fire-and-forget write — mirrors to console, then inserts to DB async. */
 function write(params: WriteParams): void {
   const safeMetadata = params.metadata ? (redactMetadata(params.metadata) as Record<string, unknown>) : undefined;
-  const prefix = `[${params.source}]`;
+  const source = redactLinkTokens(params.source);
+  const message = redactLinkTokens(params.message);
+  const prefix = `[${source}]`;
   const consoleFn = params.level === "error" ? console.error : params.level === "warn" ? console.warn : console.log;
-  consoleFn(prefix, params.message, ...(safeMetadata ? [safeMetadata] : []));
+  consoleFn(prefix, message, ...(safeMetadata ? [safeMetadata] : []));
 
-  sql`
+  const persist = async () => {
+    await sql`
     INSERT INTO logging.entries (level, source, message, metadata)
     VALUES (
       ${params.level},
-      ${params.source},
-      ${params.message},
+      ${source},
+      ${message},
       (${safeMetadata ? JSON.stringify(safeMetadata) : null}::text)::jsonb
     )
-  `.catch((err: Error) => console.error("[logging] DB write failed:", err.message));
+    `;
+  };
+  void persist().catch((err: Error) => console.error("[logging] DB write failed:", err.message));
 }
 
 /**

package/src/services/logging/redaction.ts

@@ -7,14 +7,18 @@ const SENSITIVE_KEY_PATTERN = /(password|secret|token|cookie|authorization|api[_
 
 export const REDACTED = "[REDACTED]";
 
+/** Recognizable one-time credentials are scrubbed even under ordinary metadata keys. */
+export const redactLinkTokens = (value: string): string => value.replace(/cl_[A-Za-z0-9_-]{43}/g, REDACTED);
+
 export const isSensitiveMetadataKey = (key: string): boolean => SENSITIVE_KEY_PATTERN.test(key);
 
 export const redactMetadata = (input: unknown): unknown => {
+  if (typeof input === "string") return redactLinkTokens(input);
   if (input === null || typeof input !== "object") return input;
   if (Array.isArray(input)) return input.map(redactMetadata);
   const out: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(input)) {
-    out[key] = isSensitiveMetadataKey(key) ? REDACTED : redactMetadata(value);
+    out[redactLinkTokens(key)] = isSensitiveMetadataKey(key) ? REDACTED : redactMetadata(value);
   }
   return out;
 };
@@ -60,6 +64,7 @@ export const redactSensitivePath = (pathname: string): string => {
     .split("/")
     .map((segment) => {
       const value = decodeSegment(segment);
+      if (redactLinkTokens(value) !== value) return ":token";
       if (UUID.test(value)) return ":id";
       // Dot-separated parts cover signed tokens and credential filenames such as .ics.
       // Lowercase word slugs preserve readable routes like getting-started-with-grids.

package/src/services/logging/trace.ts

@@ -1,10 +1,10 @@
 import { createHash, randomBytes } from "node:crypto";
 import type { SyncEvent } from "@k2b/sync";
-import { sql } from "bun";
 import { getProcessApplicationId } from "../../_internal/process-identity";
 import type { PaginationParams } from "../../contracts/shared";
+import { sql } from "../../runtime/clients";
 import { escapeLikePattern, parsePgJsonRecord, toPgTextArray } from "../postgres";
-import { isSensitiveMetadataKey, REDACTED, redactMetadata } from "./redaction";
+import { isSensitiveMetadataKey, REDACTED, redactLinkTokens, redactMetadata } from "./redaction";
 
 export type TraceAttributeValue = string | number | boolean | null | undefined;
 export type TraceAttributes = Record<string, TraceAttributeValue>;
@@ -499,10 +499,10 @@ const start = async (params: TraceStartParams, preservePresentation = false): Pr
     VALUES (
       ${context.traceId},
       ${context.spanId},
-      ${params.spanKey ?? null},
+      ${params.spanKey ? redactLinkTokens(params.spanKey) : null},
       ${params.parent?.spanId ?? null},
-      ${params.name},
-      ${params.source},
+      ${redactLinkTokens(params.name)},
+      ${redactLinkTokens(params.source)},
       ${params.appId ?? null},
       ${params.category ?? "custom"},
       ${params.kind ?? "internal"},
@@ -567,10 +567,10 @@ const complete = async (params: TraceCompleteParams, preservePresentation = fals
     VALUES (
       ${context.traceId},
       ${context.spanId},
-      ${params.spanKey ?? null},
+      ${params.spanKey ? redactLinkTokens(params.spanKey) : null},
       ${params.parent?.spanId ?? null},
-      ${params.name},
-      ${params.source},
+      ${redactLinkTokens(params.name)},
+      ${redactLinkTokens(params.source)},
       ${params.appId ?? null},
       ${params.category ?? "custom"},
       ${params.kind ?? "internal"},
@@ -636,7 +636,7 @@ const record = async (params: TraceRecordParams, preservePresentation = false):
     VALUES (
       ${context.traceId},
       ${context.spanId},
-      ${params.event},
+      ${redactLinkTokens(params.event)},
       ${params.severity ?? "info"},
       (${attributesJson}::text)::jsonb,
       ${body},

package/src/services/logging/web-vitals.ts

@@ -1,5 +1,5 @@
-import { sql } from "bun";
 import { z } from "zod";
+import { sql } from "../../runtime/clients";
 
 const ranges = {
   "1h": { hours: 1, bucket: 60 },

package/src/services/mandates/index.ts

@@ -1,8 +1,9 @@
 import { err, fail, ok, type PageParams, type Paginated, paginate, type Result } from "@k2b/stdlib";
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { z } from "zod";
 import type { CapabilityActionPolicy } from "../../contracts/capabilities";
 import { CapabilityAppIdSchema } from "../../contracts/capabilities";
+import { sql } from "../../runtime/clients";
 import { isAccountCategoryAllowed } from "../account-category-policy";
 import { audit } from "../audit";
 import { requireRegisteredAppAccess, resolveIssuanceAuthority } from "../identity/issue-invocation";