okengine 0.1.4

package/src/elements/store.ts

@@ -0,0 +1,99 @@
+/**
+ * Store element — data at rest.
+ *
+ * Facets: `sql` · `kv` · `files` · `index`.
+ * Drivers are protocol-named and live under `src/drivers/*`.
+ * All world access still goes through `fx`; this module only declares
+ * resources and provides runtime helpers (cache, replica routing, PII).
+ */
+
+export { store, sql, kv, files, index } from "./store/declare.ts";
+export type {
+  StoreDecl,
+  SqlStoreDecl,
+  KvStoreDecl,
+  FilesStoreDecl,
+  IndexStoreDecl,
+  SqlStoreOptions,
+  KvStoreOptions,
+  FilesStoreOptions,
+  IndexStoreOptions,
+} from "./store/declare.ts";
+
+export {
+  classify,
+  buildClassificationMap,
+  maskRows,
+  isPiiColumn,
+  tableFromSql,
+  PII_MASK,
+} from "./store/classify.ts";
+export type { MaskRowsOptions } from "./store/classify.ts";
+
+export {
+  createStoreCache,
+  computedCacheKey,
+  tier1KeysForReads,
+  resourcesTouchedByWrites,
+  isInvalidatedByWrite,
+  parseTtlMs,
+} from "./store/cache.ts";
+export type {
+  CacheTier,
+  CacheEntry,
+  InvalidationEvent,
+  StoreCache,
+} from "./store/cache.ts";
+
+export {
+  isReadOnlyStoreFlow,
+  sqlRoleForEffects,
+  resolveSqlTarget,
+} from "./store/replica.ts";
+export type { SqlBindingConfig } from "./store/replica.ts";
+
+export {
+  defineTable,
+  resolveTableName,
+  classificationsFromTable,
+  id,
+  now,
+} from "./store/table.ts";
+export type { ColumnDef, TableHandle } from "./store/table.ts";
+
+export {
+  createSqlStoreHandle,
+  resolvePkColumn,
+} from "./store/sql-session.ts";
+export type {
+  SqlStoreHandle,
+  SelectBuilder,
+  SelectFromBuilder,
+  InsertBuilder,
+  InsertValuesBuilder,
+  SqlSessionOptions,
+  WhereMap,
+} from "./store/sql-session.ts";
+
+export {
+  createStoreRuntime,
+  putTier2,
+} from "./store/runtime.ts";
+export type {
+  StoreRuntime,
+  StoreDriverBundle,
+  StoreHandle,
+  StoreInvokeContext,
+  CreateStoreRuntimeOptions,
+  SqlRuntimeBinding,
+  KvStoreFxHandle,
+  FilesStoreFxHandle,
+  IndexStoreFxHandle,
+} from "./store/runtime.ts";
+
+export {
+  fileKeyWarnings,
+  contentAddressedKey,
+  projectFileKeys,
+} from "./store/files-policy.ts";
+export type { FileKeyWarning } from "./store/files-policy.ts";

package/src/elements/vault/declare.ts

@@ -0,0 +1,143 @@
+/**
+ * Vault declaration — secret and config contracts (never values for secrets).
+ *
+ * Physics: secrets · config · environment.
+ */
+
+/** Options for {@link vault} / {@link vault.secret} / {@link vault.config}. */
+export interface VaultSecretOptions {
+  /** Human description shown in boot-gap listings. */
+  readonly description?: string;
+  /** Rotation hint (`"90d"`, …). */
+  readonly rotate?: string;
+  /** Optional schema validator (Standard Schema / zod / …). */
+  readonly schema?: unknown;
+  /** Dev-only fallback value (never used in prod boot). */
+  readonly dev?: string;
+  /**
+   * When `false`, the value is non-sensitive config — Console may show it
+   * in the clear. Defaults to `true` for secrets and `false` for config.
+   */
+  readonly sensitive?: boolean;
+}
+
+/** Declared vault contract handle. */
+export interface VaultSecretDecl {
+  /** `"secret"` is fingerprinted; `"config"` is shown in the clear. */
+  readonly kind: "secret" | "config";
+  /** Contract name (e.g. `STRIPE_KEY`). */
+  readonly name: string;
+  readonly description?: string;
+  readonly rotate?: string;
+  readonly schema?: unknown;
+  readonly dev?: string;
+  /** Whether cleartext must never leave the runtime (default by kind). */
+  readonly sensitive: boolean;
+}
+
+/**
+ * Declare a vault secret contract (fingerprinted — never revealed).
+ *
+ * @param name - Secret name
+ * @param options - Description / rotate / schema / dev fallback
+ */
+function declareSecret(
+  name: string,
+  options: VaultSecretOptions = {},
+): VaultSecretDecl {
+  if (!name) {
+    throw new TypeError("vault.secret: name is required");
+  }
+  return {
+    kind: "secret",
+    name,
+    sensitive: options.sensitive ?? true,
+    ...(options.description !== undefined
+      ? { description: options.description }
+      : {}),
+    ...(options.rotate !== undefined ? { rotate: options.rotate } : {}),
+    ...(options.schema !== undefined ? { schema: options.schema } : {}),
+    ...(options.dev !== undefined ? { dev: options.dev } : {}),
+  };
+}
+
+/**
+ * Declare a non-sensitive config contract (shown in the clear in Console).
+ *
+ * @param name - Config name
+ * @param options - Description / schema / dev fallback
+ */
+function declareConfig(
+  name: string,
+  options: VaultSecretOptions = {},
+): VaultSecretDecl {
+  if (!name) {
+    throw new TypeError("vault.config: name is required");
+  }
+  return {
+    kind: "config",
+    name,
+    sensitive: options.sensitive ?? false,
+    ...(options.description !== undefined
+      ? { description: options.description }
+      : {}),
+    ...(options.rotate !== undefined ? { rotate: options.rotate } : {}),
+    ...(options.schema !== undefined ? { schema: options.schema } : {}),
+    ...(options.dev !== undefined ? { dev: options.dev } : {}),
+  };
+}
+
+/**
+ * Marker prefix for {@link vault.fromStack} dev fallbacks.
+ * Resolved from `.env.stack` by `oke dev --stack` / vault boot.
+ */
+export const FROM_STACK_PREFIX = "__oke_from_stack__:";
+
+/**
+ * Dev fallback that reads the URL built by the image recipe for `role`.
+ * The kernel never sees the underlying env-var names — only the URL.
+ *
+ * @param role - Image role (`store.sql`, …)
+ */
+export function fromStack(role: string): string {
+  if (!role) throw new TypeError("vault.fromStack: role is required");
+  return `${FROM_STACK_PREFIX}${role}`;
+}
+
+/**
+ * Whether a dev fallback is a {@link fromStack} marker.
+ *
+ * @param value - Candidate
+ */
+export function isFromStack(value: string): boolean {
+  return value.startsWith(FROM_STACK_PREFIX);
+}
+
+/**
+ * Role encoded in a {@link fromStack} marker.
+ *
+ * @param value - Marker from {@link fromStack}
+ */
+export function fromStackRole(value: string): string {
+  if (!isFromStack(value)) {
+    throw new TypeError(`vault: not a fromStack marker: ${value}`);
+  }
+  return value.slice(FROM_STACK_PREFIX.length);
+}
+
+/**
+ * Vault element — `vault("NAME", opts)` · `vault.secret` · `vault.config`.
+ *
+ * A declaration is a contract, not a value. Values resolve at boot through
+ * the configured driver chain.
+ */
+export const vault: {
+  (name: string, options?: VaultSecretOptions): VaultSecretDecl;
+  secret(name: string, options?: VaultSecretOptions): VaultSecretDecl;
+  config(name: string, options?: VaultSecretOptions): VaultSecretDecl;
+  fromStack(role: string): string;
+} = Object.assign(declareSecret, {
+  secret: declareSecret,
+  config: declareConfig,
+  fromStack,
+});

package/src/elements/vault/fingerprint.ts

@@ -0,0 +1,30 @@
+/**
+ * Secret fingerprints — Console / traces show these, never cleartext.
+ */
+
+/**
+ * SHA-256 fingerprint of a secret value (first 16 hex chars).
+ *
+ * @param value - Cleartext secret
+ */
+export async function fingerprintSecret(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(value),
+  );
+  const hex = [...new Uint8Array(digest)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return `sha256:${hex.slice(0, 16)}`;
+}
+
+/**
+ * Synchronous fingerprint using Bun's hasher when available (boot / logs).
+ *
+ * @param value - Cleartext secret
+ */
+export function fingerprintSecretSync(value: string): string {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(value);
+  return `sha256:${hasher.digest("hex").slice(0, 16)}`;
+}

package/src/elements/vault/redact.ts

@@ -0,0 +1,52 @@
+/**
+ * Automatic secret redaction for logs and traces.
+ */
+
+/** Default mask token (same family as store PII mask). */
+export const SECRET_MASK = "[redacted:secret]";
+
+/**
+ * Build a redactor that replaces known secret values (and substrings) in
+ * strings and deep-clones objects with values scrubbed.
+ *
+ * @param secrets - Cleartext values currently loaded
+ */
+export function createSecretRedactor(
+  secrets: Iterable<string>,
+): {
+  /** Redact a free-form string. */
+  redactString(input: string): string;
+  /** Deep-redact a JSON-like value. */
+  redact(value: unknown): unknown;
+} {
+  const values = [...secrets]
+    .filter((v) => v.length > 0)
+    .sort((a, b) => b.length - a.length);
+
+  function redactString(input: string): string {
+    let out = input;
+    for (const v of values) {
+      if (out.includes(v)) {
+        out = out.split(v).join(SECRET_MASK);
+      }
+    }
+    return out;
+  }
+
+  function redact(value: unknown): unknown {
+    if (typeof value === "string") return redactString(value);
+    if (value === null || value === undefined) return value;
+    if (Array.isArray(value)) return value.map(redact);
+    if (typeof value === "object") {
+      const obj = value as Record<string, unknown>;
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(obj)) {
+        out[k] = redact(v);
+      }
+      return out;
+    }
+    return value;
+  }
+
+  return { redactString, redact };
+}