okengine 0.1.4

package/src/auth/index.ts

@@ -0,0 +1,112 @@
+/**
+ * Auth: built-in flagship (hybrid JWT + revocable refresh, ABAC, MFA)
+ * plus a provider seam. Subpath: `okengine/auth`.
+ *
+ * Two planes — `fx.operator` vs `fx.auth` — permanently separated.
+ */
+
+export { auth, type AuthPluginOptions } from "./plugin.ts";
+
+export {
+  assertPlaneAccess,
+  operatorPrincipal,
+  userPrincipal,
+  CrossPlaneError,
+  type AuthPlane,
+  type OperatorPrincipal,
+  type Principal,
+  type UserPrincipal,
+} from "./planes.ts";
+
+export {
+  assertCrossPlane,
+  checkCrossPlane,
+  type CrossPlaneDiagnostic,
+  type PlaneSourceFile,
+} from "./cross-plane.ts";
+
+export {
+  attenuateScopes,
+  assertAttenuated,
+  expandHeldScopes,
+  grantableScopes,
+  AttenuationError,
+  type AttenuationResult,
+} from "./attenuation.ts";
+
+export {
+  createApiKey,
+  createApiKeyStore,
+  authenticateApiKey,
+  hashApiKeySecret,
+  revokeApiKey,
+  rotateApiKey,
+  type ApiKeyStore,
+  type CreateApiKeyOptions,
+  type CreatedApiKey,
+} from "./api-keys.ts";
+
+export {
+  createOperatorInviteStore,
+  createOperatorInvite,
+  isInviteExpired,
+  INVITE_TTL_MS,
+  type CreateInviteOptions,
+  type OperatorInviteStore,
+} from "./invites.ts";
+
+export {
+  createSessionStore,
+  issueSession,
+  issueSessionWithScopes,
+  rotateRefresh,
+  verifyAccess,
+  revokeFamily,
+  bindSessionScopes,
+  bindSessionAudience,
+  ACCESS_TTL_MS,
+  REFRESH_TTL_MS,
+  SessionError,
+  type AccessClaims,
+  type IssuedSession,
+  type SessionCrypto,
+  type SessionStore,
+  type VerifyAccessOptions,
+} from "./sessions.ts";
+
+export {
+  createOperatorStore,
+  createOperator,
+  removeOperatorCredential,
+  linkOperatorSso,
+  authenticateOperator,
+  OperatorError,
+  type CreateOperatorOptions,
+  type OperatorStore,
+} from "./operator.ts";
+
+export {
+  createRoleStore,
+  upsertRole,
+  setRoleGrants,
+  scopesForRoles,
+  listRoleGrants,
+  type RoleStore,
+} from "./roles.ts";
+
+export { invokeAs, type InvokeAsOptions } from "./invoke-as.ts";
+
+export {
+  AUTH_TABLES,
+  type ApiKeyRow,
+  type IdentityRow,
+  type OperatorCredentialRow,
+  type OperatorInviteRow,
+  type OperatorRow,
+  type OperatorSsoLinkRow,
+  type RefreshTokenRow,
+  type RoleGrantRow,
+  type RoleRow,
+  type SessionRow,
+  type TablePlane,
+} from "./tables.ts";

package/src/auth/invites.ts

@@ -0,0 +1,66 @@
+/**
+ * Operator invitations — invite-only plane (console §2.2 · §9.14).
+ */
+
+import type { OperatorInviteRow } from "./tables.ts";
+
+/** Default invitation TTL (7 days). */
+export const INVITE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** In-memory operator invite store. */
+export interface OperatorInviteStore {
+  invites: Map<string, OperatorInviteRow>;
+}
+
+/**
+ * Create an empty invite store.
+ */
+export function createOperatorInviteStore(): OperatorInviteStore {
+  return { invites: new Map() };
+}
+
+/** Options when creating an invitation. */
+export interface CreateInviteOptions {
+  readonly email: string;
+  readonly invitedBy: string;
+  readonly id?: string;
+  readonly ttlMs?: number;
+  readonly now?: () => number;
+}
+
+/**
+ * Create a pending operator invitation.
+ *
+ * @param store - Invite store
+ * @param options - Invite fields
+ */
+export function createOperatorInvite(
+  store: OperatorInviteStore,
+  options: CreateInviteOptions,
+): OperatorInviteRow {
+  const now = options.now ?? (() => Date.now());
+  const t = now();
+  const row: OperatorInviteRow = {
+    id: options.id ?? crypto.randomUUID(),
+    email: options.email,
+    invitedBy: options.invitedBy,
+    createdAt: t,
+    expiresAt: t + (options.ttlMs ?? INVITE_TTL_MS),
+    acceptedAt: null,
+  };
+  store.invites.set(row.id, row);
+  return row;
+}
+
+/**
+ * Whether an invite is expired and still unaccepted.
+ *
+ * @param row - Invite row
+ * @param now - Clock
+ */
+export function isInviteExpired(
+  row: OperatorInviteRow,
+  now: () => number = () => Date.now(),
+): boolean {
+  return row.acceptedAt === null && row.expiresAt <= now();
+}

package/src/auth/invoke-as.ts

@@ -0,0 +1,49 @@
+/**
+ * `console:flows:invoke-as` — attenuated exactly like an API key.
+ *
+ * An operator cannot assume a scope set they could not grant.
+ * Impersonating a real user is development-only.
+ *
+ * @see docs/spec/console.md §10.4
+ */
+
+import { assertAttenuated } from "./attenuation.ts";
+import { userPrincipal, type UserPrincipal } from "./planes.ts";
+
+/** Options for invoke-as. */
+export interface InvokeAsOptions {
+  /** Operator's own scopes (attenuation ceiling). */
+  readonly operatorScopes: ReadonlySet<string> | Iterable<string>;
+  /** Requested application scopes for the assumed principal. */
+  readonly scopes: readonly string[];
+  /** Synthetic user id (required). */
+  readonly userId: string;
+  /**
+   * When true, allows binding to a real identity id.
+   * Impersonating a real user is development-only.
+   */
+  readonly impersonateRealUser?: boolean;
+  /** Production / development flag. */
+  readonly development?: boolean;
+}
+
+/**
+ * Build an attenuated user principal for console invoke-as.
+ *
+ * @param options - Operator ceiling + requested scopes
+ */
+export function invokeAs(options: InvokeAsOptions): UserPrincipal {
+  assertAttenuated(options.operatorScopes, options.scopes, "invoke-as");
+
+  if (options.impersonateRealUser && !options.development) {
+    throw new Error(
+      "invoke-as: impersonating a real user is development-only",
+    );
+  }
+
+  return userPrincipal({
+    userId: options.userId,
+    scopes: options.scopes,
+    verified: true,
+  });
+}

package/src/auth/operator.ts

@@ -0,0 +1,178 @@
+/**
+ * Operator plane — local credential always present; SSO is additive.
+ *
+ * The local password hash can never be removed. Enterprise SSO links a
+ * provider as an *additional* authentication method.
+ *
+ * @see docs/spec/console.md §2.2–2.3
+ */
+
+import { createBunCrypto } from "../runtime/primitives.ts";
+import type {
+  OperatorCredentialRow,
+  OperatorRow,
+  OperatorSsoLinkRow,
+} from "./tables.ts";
+
+/** Operator-plane store. */
+export interface OperatorStore {
+  operators: Map<string, OperatorRow>;
+  credentials: Map<string, OperatorCredentialRow>;
+  ssoLinks: Map<string, OperatorSsoLinkRow[]>;
+  roles: Map<string, string[]>;
+}
+
+/**
+ * Create an empty operator store.
+ */
+export function createOperatorStore(): OperatorStore {
+  return {
+    operators: new Map(),
+    credentials: new Map(),
+    ssoLinks: new Map(),
+    roles: new Map(),
+  };
+}
+
+/** Options for creating an operator. */
+export interface CreateOperatorOptions {
+  readonly email: string;
+  readonly name: string;
+  readonly password: string;
+  readonly invitedBy?: string | null;
+  readonly id?: string;
+  readonly roles?: readonly string[];
+}
+
+/**
+ * Create an operator with a mandatory local credential.
+ *
+ * @param store - Operator store
+ * @param options - Identity + password
+ */
+export async function createOperator(
+  store: OperatorStore,
+  options: CreateOperatorOptions,
+): Promise<OperatorRow> {
+  const crypto = createBunCrypto();
+  const id = options.id ?? crypto.randomUUID();
+  const row: OperatorRow = {
+    id,
+    email: options.email,
+    name: options.name,
+    status: "active",
+    mfaEnabled: false,
+    invitedBy: options.invitedBy ?? null,
+    lastSeenAt: null,
+  };
+  store.operators.set(id, row);
+  store.credentials.set(id, {
+    operatorId: id,
+    passwordHash: await crypto.hashPassword(options.password, "argon2id"),
+    loginEnabled: true,
+  });
+  store.ssoLinks.set(id, []);
+  store.roles.set(id, [...(options.roles ?? [])]);
+  return row;
+}
+
+/**
+ * Refuse removal of the local credential — SSO never becomes the sole path.
+ *
+ * @param store - Operator store
+ * @param operatorId - Operator id
+ */
+export function removeOperatorCredential(
+  store: OperatorStore,
+  operatorId: string,
+): never {
+  void store;
+  void operatorId;
+  throw new OperatorError(
+    "operator local credential cannot be removed; SSO is additive only",
+  );
+}
+
+/**
+ * Link an SSO identity as an additional method (local credential remains).
+ *
+ * @param store - Operator store
+ * @param operatorId - Operator id
+ * @param provider - Provider id
+ * @param subject - Provider subject
+ */
+export function linkOperatorSso(
+  store: OperatorStore,
+  operatorId: string,
+  provider: string,
+  subject: string,
+): OperatorSsoLinkRow {
+  if (!store.operators.has(operatorId)) {
+    throw new OperatorError(`unknown operator: ${operatorId}`);
+  }
+  if (!store.credentials.has(operatorId)) {
+    throw new OperatorError(
+      "operator is missing local credential — invariant violated",
+    );
+  }
+  const link: OperatorSsoLinkRow = { operatorId, provider, subject };
+  const list = store.ssoLinks.get(operatorId) ?? [];
+  list.push(link);
+  store.ssoLinks.set(operatorId, list);
+  return link;
+}
+
+/**
+ * Dummy argon2id hash used when no credential exists so missing-user and
+ * bad-password paths both pay a verify round-trip (timing oracle defence).
+ */
+let dummyPasswordHash: string | null = null;
+
+async function dummyHash(
+  crypto: ReturnType<typeof createBunCrypto>,
+): Promise<string> {
+  if (dummyPasswordHash === null) {
+    dummyPasswordHash = await crypto.hashPassword(
+      "oke-operator-timing-dummy",
+      "argon2id",
+    );
+  }
+  return dummyPasswordHash;
+}
+
+/**
+ * Verify local password login.
+ *
+ * Always runs a password verify (against a dummy hash when the account is
+ * missing / disabled) so response time does not reveal account existence.
+ *
+ * @param store - Operator store
+ * @param email - Email
+ * @param password - Password
+ */
+export async function authenticateOperator(
+  store: OperatorStore,
+  email: string,
+  password: string,
+): Promise<OperatorRow | null> {
+  const crypto = createBunCrypto();
+  const op = [...store.operators.values()].find((o) => o.email === email);
+  const cred =
+    op && op.status === "active" ? store.credentials.get(op.id) : undefined;
+  const hash =
+    cred && cred.loginEnabled ? cred.passwordHash : await dummyHash(crypto);
+  const ok = await crypto.verifyPassword(password, hash);
+  if (!ok || !op || !cred || !cred.loginEnabled || op.status !== "active") {
+    return null;
+  }
+  return op;
+}
+
+/** Operator-plane error. */
+export class OperatorError extends Error {
+  /** @param message - Diagnostic */
+  constructor(message: string) {
+    super(message);
+    this.name = "OperatorError";
+  }
+}

package/src/auth/planes.ts

@@ -0,0 +1,102 @@
+/**
+ * Two planes, permanently separated — operator vs user.
+ *
+ * Cross-plane invocation is a compile error. Principals never mix:
+ * `fx.operator` on the Console plane, `fx.auth` on the application plane.
+ *
+ * @see docs/spec/console.md §2.2
+ */
+
+/** Auth plane identifiers. */
+export type AuthPlane = "user" | "operator";
+
+/** Brand so user and operator principals are not assignable. */
+const planeBrand: unique symbol = Symbol("oke.plane");
+
+/** User-plane principal (`fx.auth`). */
+export interface UserPrincipal {
+  readonly [planeBrand]: "user";
+  readonly plane: "user";
+  readonly userId: string;
+  readonly scopes: ReadonlySet<string>;
+  readonly verified: boolean;
+  readonly roles: readonly string[];
+}
+
+/** Operator-plane principal (`fx.operator`). */
+export interface OperatorPrincipal {
+  readonly [planeBrand]: "operator";
+  readonly plane: "operator";
+  readonly id: string;
+  readonly scopes: ReadonlySet<string>;
+  readonly roles: readonly string[];
+}
+
+/** Any principal — discriminated by `plane`. */
+export type Principal = UserPrincipal | OperatorPrincipal;
+
+/**
+ * Create a user-plane principal.
+ *
+ * @param fields - Identity fields
+ */
+export function userPrincipal(fields: {
+  readonly userId: string;
+  readonly scopes?: Iterable<string>;
+  readonly verified?: boolean;
+  readonly roles?: readonly string[];
+}): UserPrincipal {
+  return {
+    [planeBrand]: "user",
+    plane: "user",
+    userId: fields.userId,
+    scopes: new Set(fields.scopes ?? []),
+    verified: fields.verified ?? false,
+    roles: fields.roles ?? [],
+  };
+}
+
+/**
+ * Create an operator-plane principal.
+ *
+ * @param fields - Identity fields
+ */
+export function operatorPrincipal(fields: {
+  readonly id: string;
+  readonly scopes?: Iterable<string>;
+  readonly roles?: readonly string[];
+}): OperatorPrincipal {
+  return {
+    [planeBrand]: "operator",
+    plane: "operator",
+    id: fields.id,
+    scopes: new Set(fields.scopes ?? []),
+    roles: fields.roles ?? [],
+  };
+}
+
+/**
+ * Type-level / runtime guard: application principals cannot reach console flows.
+ *
+ * @param principal - Acting principal
+ * @param flowPlane - Target flow plane
+ */
+export function assertPlaneAccess(
+  principal: Principal,
+  flowPlane: AuthPlane,
+): void {
+  if (principal.plane === "user" && flowPlane === "operator") {
+    throw new CrossPlaneError(
+      "application principal cannot reach a console (operator) flow",
+    );
+  }
+}
+
+/** Cross-plane invocation error (also raised at compile time). */
+export class CrossPlaneError extends Error {
+  /** @param message - Diagnostic */
+  constructor(message: string) {
+    super(message);
+    this.name = "CrossPlaneError";
+  }
+}

package/src/auth/plugin.ts

@@ -0,0 +1,44 @@
+/**
+ * Builtin auth plugin — hybrid session, two planes, roles as data.
+ *
+ * Uses only the public plugin API (unified-theory §14).
+ */
+
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import { AUTH_TABLES } from "./tables.ts";
+
+/** Options for {@link auth}. */
+export interface AuthPluginOptions {
+  /** HMAC secret for access tokens (required in production). */
+  readonly secret?: string;
+  /** Access-token TTL override (ms). */
+  readonly accessTtlMs?: number;
+  /** Refresh-token TTL override (ms). */
+  readonly refreshTtlMs?: number;
+}
+
+/**
+ * Builtin auth plugin.
+ *
+ * @param options - Session crypto options
+ */
+export function auth(options: AuthPluginOptions = {}): PluginDef {
+  let builder = plugin("auth", { version: "0.0.1", config: options }).hook(
+    "onAuth",
+    (_ctx) => {
+      /* principals resolved by session / API key middleware at runtime */
+    },
+  );
+
+  for (const name of Object.values(AUTH_TABLES)) {
+    builder = builder.table(name, {
+      plane: name.includes("operator")
+        ? "operator"
+        : name.includes("identit") || name === AUTH_TABLES.credentials
+          ? "user"
+          : "shared",
+    });
+  }
+
+  return builder.needs("store.sql");
+}

package/src/auth/roles.ts

@@ -0,0 +1,84 @@
+/**
+ * Roles are data — any Module:Action set can be assigned without redeploy.
+ *
+ * @see docs/spec/console.md §3.2
+ */
+
+import type { AuthPlane } from "./planes.ts";
+import type { RoleGrantRow, RoleRow } from "./tables.ts";
+
+/** In-memory role store for tests / builtin auth. */
+export interface RoleStore {
+  roles: Map<string, RoleRow>;
+  grants: Map<string, Set<string>>;
+}
+
+/**
+ * Create an empty role store.
+ */
+export function createRoleStore(): RoleStore {
+  return { roles: new Map(), grants: new Map() };
+}
+
+/**
+ * Upsert a role (data, not code).
+ *
+ * @param store - Role store
+ * @param role - Role row
+ */
+export function upsertRole(store: RoleStore, role: RoleRow): void {
+  store.roles.set(role.id, role);
+  if (!store.grants.has(role.id)) store.grants.set(role.id, new Set());
+}
+
+/**
+ * Replace grants for a role with Module:Action pairs.
+ *
+ * @param store - Role store
+ * @param roleId - Role id
+ * @param actions - Module:Action pairs
+ */
+export function setRoleGrants(
+  store: RoleStore,
+  roleId: string,
+  actions: readonly string[],
+): void {
+  if (!store.roles.has(roleId)) {
+    throw new Error(`unknown role: ${roleId}`);
+  }
+  store.grants.set(roleId, new Set(actions));
+}
+
+/**
+ * Resolve the union of Module:Action scopes for role ids on a plane.
+ *
+ * @param store - Role store
+ * @param roleIds - Role ids
+ * @param plane - Plane filter (roles from the other plane are ignored)
+ */
+export function scopesForRoles(
+  store: RoleStore,
+  roleIds: readonly string[],
+  plane: AuthPlane,
+): Set<string> {
+  const scopes = new Set<string>();
+  for (const id of roleIds) {
+    const role = store.roles.get(id);
+    if (!role || role.plane !== plane) continue;
+    for (const a of store.grants.get(id) ?? []) scopes.add(a);
+  }
+  return scopes;
+}
+
+/**
+ * Snapshot grants as rows.
+ *
+ * @param store - Role store
+ */
+export function listRoleGrants(store: RoleStore): RoleGrantRow[] {
+  const out: RoleGrantRow[] = [];
+  for (const [roleId, actions] of store.grants) {
+    for (const action of actions) out.push({ roleId, action });
+  }
+  return out;
+}