okengine 0.15.2 → 0.17.0

package/src/auth/auth.test.ts

@@ -114,6 +114,62 @@ describe("auth plugin", () => {
   });
 });
 
+describe("API key allowlist", () => {
+  test("hostname entry matches the resolved client IP", async () => {
+    const { authenticateApiKey } = await import("./api-keys.ts");
+    const store = createApiKeyStore();
+    const created = await createApiKey(store, {
+      plane: "user",
+      name: "ci",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      ipAllowlist: ["ci.example.com"],
+    });
+    const lookup = async (host: string) => (host === "ci.example.com" ? ["203.0.113.10"] : []);
+    expect(
+      await authenticateApiKey(store, created.secret, {
+        ip: "203.0.113.10",
+        lookup,
+      }),
+    ).not.toBeNull();
+    expect(
+      await authenticateApiKey(store, created.secret, {
+        ip: "198.51.100.7",
+        lookup,
+      }),
+    ).toBeNull();
+  });
+
+  test("hostname lookup failure is closed", async () => {
+    const { authenticateApiKey } = await import("./api-keys.ts");
+    const store = createApiKeyStore();
+    const created = await createApiKey(store, {
+      plane: "user",
+      name: "ci",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      ipAllowlist: ["ci.example.com", "203.0.113.10"],
+    });
+    const lookup = async () => {
+      throw new Error("nxdomain");
+    };
+    expect(
+      await authenticateApiKey(store, created.secret, {
+        ip: "203.0.113.10",
+        lookup,
+      }),
+    ).not.toBeNull();
+    expect(
+      await authenticateApiKey(store, created.secret, {
+        ip: "198.51.100.7",
+        lookup,
+      }),
+    ).toBeNull();
+  });
+});
+
 describe("API key attenuation", () => {
   test("key cannot be created with a scope its creator lacks", async () => {
     const store = createApiKeyStore();

package/src/auth/config.ts

@@ -6,7 +6,7 @@
 
 import type { PasswordHashOptions } from "../runtime/types.ts";
 import type { SessionStore } from "./sessions.ts";
-import type { ApiKeyStore } from "./api-keys.ts";
+import { createApiKeyStore, type ApiKeyStore } from "./api-keys.ts";
 import type { BreachCheckFn } from "./breach-check.ts";
 import type { PasswordPolicyOptions } from "./password-policy.ts";
 import {
@@ -16,6 +16,12 @@ import {
   type ResolvedAuthSchema,
 } from "./schema.ts";
 import { sessionCryptoFromAuthOptions, type AuthSessionOptions } from "./plugin.ts";
+import { createTenantStore, type TenantStore } from "./tenants.ts";
+import {
+  resolveTenantAuth,
+  type ResolvedTenantAuth,
+  type TenantAuthOptions,
+} from "./tenant-config.ts";
 
 /** Email + password method knobs. */
 export interface EmailAndPasswordOptions {
@@ -111,10 +117,19 @@ export interface GateAuthOptions extends AuthSchemaOptions {
    */
   readonly sessions?: SessionStore;
   /**
-   * In-memory API key store for Bearer key auth (tests / embedding).
-   * Distinct from schema `apiKeys` table options.
+   * Shared API key store. Created automatically when omitted
+   * (`gate.auth.secret` is the HMAC pepper).
    */
   readonly apiKeyStore?: ApiKeyStore;
+  /**
+   * Multi-tenancy as an identity dimension. `true` enables defaults
+   * (`source: "claim"`, `required: false`). Off when omitted.
+   */
+  readonly tenant?: boolean | TenantAuthOptions;
+  /**
+   * Shared tenant registry. Created automatically when {@link tenant} is on.
+   */
+  readonly tenantStore?: TenantStore;
   /** Injectable clock. */
   readonly now?: () => number;
 }
@@ -170,7 +185,9 @@ export interface ResolvedGateAuth {
   };
   readonly hooks: AuthDatabaseHooks | undefined;
   readonly sessions: SessionStore | undefined;
-  readonly apiKeyStore: ApiKeyStore | undefined;
+  readonly apiKeyStore: ApiKeyStore;
+  readonly tenant: ResolvedTenantAuth | undefined;
+  readonly tenantStore: TenantStore | undefined;
   readonly now: (() => number) | undefined;
 }
 
@@ -278,7 +295,9 @@ export function resolveGateAuth(options: ResolveGateAuthOptions): ResolvedGateAu
     },
     hooks: auth.hooks,
     sessions: auth.sessions,
-    apiKeyStore: auth.apiKeyStore,
+    apiKeyStore: auth.apiKeyStore ?? createApiKeyStore({ pepper: secret }),
+    tenant: auth.tenant ? resolveTenantAuth(auth.tenant) : undefined,
+    tenantStore: auth.tenant ? (auth.tenantStore ?? createTenantStore()) : auth.tenantStore,
     now: auth.now,
   };
 }

package/src/auth/index.ts

@@ -161,17 +161,41 @@ export {
 } from "./attenuation.ts";
 
 export {
+  AUTH_API_KEYS_RESOURCE,
+  allowlistAllowsIp,
+  authenticateApiKey,
+  clientIpFromRequest,
   createApiKey,
   createApiKeyStore,
-  authenticateApiKey,
+  getApiKey,
   hashApiKeySecret,
+  listApiKeys,
   revokeApiKey,
   rotateApiKey,
+  toApiKeyPublicRow,
+  updateApiKey,
+  type AllowlistLookup,
+  type ApiKeyPublicRow,
   type ApiKeyStore,
+  type AuthenticateApiKeyOptions,
   type CreateApiKeyOptions,
+  type CreateApiKeyStoreOptions,
   type CreatedApiKey,
+  type UpdateApiKeyOptions,
 } from "./api-keys.ts";
 
+export {
+  apiKeySqlExec,
+  bindApiKeySqlPersist,
+  bindHostApiKeySql,
+  bindHostApiKeySqlFromStore,
+  ensureApiKeyTable,
+  hydrateApiKeyStore,
+  persistApiKeyRow,
+  type ApiKeySqlExec,
+  type HostApiKeySqlRuntime,
+} from "./api-key-sql.ts";
+
 export {
   createOperatorInviteStore,
   createOperatorInvite,
@@ -236,4 +260,41 @@ export {
   type RoleRow,
   type SessionRow,
   type TablePlane,
+  type TenantMemberRow,
+  type TenantRoleRow,
+  type TenantRow,
 } from "./tables.ts";
+
+export { AUTH_TENANT_TABLES } from "./tenant-tables.ts";
+
+export {
+  AUTH_TENANTS_RESOURCE,
+  DEFAULT_TENANT_ROLE,
+  TenantError,
+  addMember,
+  createTenant,
+  createTenantStore,
+  deleteTenant,
+  getMember,
+  isMember,
+  listMembers,
+  listTenantIds,
+  listTenantsForUser,
+  removeMember,
+  tenantRoleScopeFailure,
+  tenantScopesForMember,
+  upsertTenantRole,
+  type CreateTenantOptions,
+  type TenantPublicRow,
+  type TenantStore,
+  type TenantStoreHooks,
+  type UpsertTenantRoleOptions,
+} from "./tenants.ts";
+
+export {
+  resolveTenantAuth,
+  type ResolvedTenantAuth,
+  type TenantAuthOptions,
+  type TenantResolveContext,
+  type TenantSource,
+} from "./tenant-config.ts";

package/src/auth/plugin.ts

@@ -9,6 +9,7 @@ import { plugin, type PluginDef } from "../kernel/plugin.ts";
 import type { BreachCheckFn } from "./breach-check.ts";
 import type { PasswordPolicyOptions } from "./password-policy.ts";
 import { AUTH_TABLES } from "./tables.ts";
+import { AUTH_TENANT_TABLES } from "./tenant-tables.ts";
 
 /** Session knobs beyond raw access/refresh TTLs. */
 export interface AuthSessionOptions {
@@ -83,7 +84,11 @@ export function auth(options: AuthPluginOptions = {}): PluginDef {
     /* principals resolved by session / API key middleware at runtime */
   });
 
-  for (const name of Object.values(AUTH_TABLES)) {
+  const tables: readonly string[] = [
+    ...Object.values(AUTH_TABLES),
+    ...Object.values(AUTH_TENANT_TABLES),
+  ];
+  for (const name of tables) {
     builder = builder.table(name, undefined, {
       plane: name.includes("operator")
         ? "operator"

package/src/auth/schema.ts

@@ -105,6 +105,10 @@ export const AUTH_MODEL_DEFAULT_FIELDS: Readonly<
     name: "name",
     scopes: "scopes",
     expiresAt: "expires_at",
+    rateLimit: "rate_limit",
+    ipAllowlist: "ip_allowlist",
+    creatorId: "creator_id",
+    creatorScopes: "creator_scopes",
     createdAt: "created_at",
     lastUsedAt: "last_used_at",
     revokedAt: "revoked_at",
@@ -190,6 +194,10 @@ const CORE_SQL_TYPES: Readonly<Record<string, AuthColumnSqlType>> = {
   scopes: "TEXT",
   audience: "TEXT",
   lastUsedAt: "INTEGER",
+  rateLimit: "TEXT",
+  ipAllowlist: "TEXT",
+  creatorId: "TEXT",
+  creatorScopes: "TEXT",
 };
 
 /**

package/src/auth/sessions.ts

@@ -43,6 +43,11 @@ export interface AccessClaims {
    * Validated when the verifier supplies {@link VerifyAccessOptions.audience}.
    */
   readonly aud?: string;
+  /**
+   * Active tenant for this access token (request-scoped).
+   * Never stored on the session row — switching issues a new token pair.
+   */
+  readonly tid?: string;
 }
 
 /** Options for {@link createSessionStore}. */
@@ -106,6 +111,8 @@ export async function issueSession(
     readonly id: string;
     readonly plane: AuthPlane;
     readonly scopes: Iterable<string>;
+    /** Optional tenant claim (not stored on the session row). */
+    readonly tenantId?: string | null;
   },
 ): Promise<IssuedSession> {
   const now = crypto.now ?? (() => Date.now());
@@ -136,6 +143,7 @@ export async function issueSession(
   store.sessions.set(sessionId, session);
 
   const refreshRaw = `rt_${cryptoRandomId()}`;
+  const tid = principal.tenantId ?? undefined;
   const refreshRow: RefreshTokenRow = {
     id: cryptoRandomId(),
     sessionId,
@@ -144,6 +152,7 @@ export async function issueSession(
     expiresAt: t + refreshTtl,
     usedAt: null,
     revokedAt: null,
+    ...(tid !== undefined && tid !== "" ? { tid } : {}),
   };
   store.refresh.set(refreshRow.id, refreshRow);
 
@@ -156,6 +165,7 @@ export async function issueSession(
     iat: t,
     exp: accessExpiresAt,
     ...(crypto.audience !== undefined ? { aud: crypto.audience } : {}),
+    ...(tid !== undefined && tid !== "" ? { tid } : {}),
   });
 
   return { session, accessToken, refreshToken: refreshRaw, accessExpiresAt };
@@ -211,6 +221,7 @@ export async function rotateRefresh(
   const refreshTtl = crypto.refreshTtlMs ?? REFRESH_TTL_MS;
 
   const newRefreshRaw = `rt_${cryptoRandomId()}`;
+  const rotatedTid = existing.tid;
   const newRefresh: RefreshTokenRow = {
     id: cryptoRandomId(),
     sessionId: session.id,
@@ -219,6 +230,9 @@ export async function rotateRefresh(
     expiresAt: t + refreshTtl,
     usedAt: null,
     revokedAt: null,
+    ...(rotatedTid !== undefined && rotatedTid !== null && rotatedTid !== ""
+      ? { tid: rotatedTid }
+      : {}),
   };
   store.refresh.set(newRefresh.id, newRefresh);
 
@@ -231,6 +245,9 @@ export async function rotateRefresh(
     iat: t,
     exp: accessExpiresAt,
     ...(session.audience !== undefined ? { aud: session.audience } : {}),
+    ...(rotatedTid !== undefined && rotatedTid !== null && rotatedTid !== ""
+      ? { tid: rotatedTid }
+      : {}),
   });
 
   return {
@@ -291,6 +308,7 @@ export async function issueSessionWithScopes(
     readonly id: string;
     readonly plane: AuthPlane;
     readonly scopes: Iterable<string>;
+    readonly tenantId?: string | null;
   },
 ): Promise<IssuedSession> {
   return issueSession(store, crypto, principal);

package/src/auth/tables.ts

@@ -98,6 +98,8 @@ export interface ApiKeyRow {
   lastUsedAt: number | null;
   /** Epoch-ms when revoked; `null` while active. */
   revokedAt: number | null;
+  /** Optional tenant claim (tier-1 API-key tenancy). */
+  tenantId?: string | null;
 }
 
 /** Pending operator invitation (invite-only plane). */
@@ -136,4 +138,34 @@ export interface RefreshTokenRow {
   expiresAt: number;
   usedAt: number | null;
   revokedAt: number | null;
+  /** Tenant id stamped on this refresh row (request-scoped; not on the session). */
+  tid?: string | null;
+}
+
+/** Tenant registry row. */
+export interface TenantRow {
+  id: string;
+  name: string;
+  slug: string | null;
+  createdAt: number;
+  createdBy: string;
+}
+
+/** N:N membership — one user, many tenants; one tenant, many users. */
+export interface TenantMemberRow {
+  id: string;
+  tenantId: string;
+  userId: string;
+  /** Tenant role name (expanded via {@link TenantRoleRow}). */
+  role: string;
+  createdAt: number;
+}
+
+/** Tenant-scoped role → application scope names. */
+export interface TenantRoleRow {
+  tenantId: string;
+  roleName: string;
+  scopes: string[];
+  createdAt: number;
+  updatedAt: number;
 }

package/src/auth/tenant-config.ts

@@ -0,0 +1,74 @@
+/**
+ * `gate.auth.tenant` config — identity dimension opt-in.
+ */
+
+/** How the request names a tenant. */
+export type TenantSource = "claim" | "header" | "subdomain" | "resolve";
+
+/** Public `gate.auth.tenant` bag (boolean shorthand or options). */
+export interface TenantAuthOptions {
+  /**
+   * Pure B2B: every user-plane request needs a tenant.
+   * Default `false` (B2C+B2B coexistence).
+   */
+  readonly required?: boolean;
+  /** Resolution source. Default `"claim"`. */
+  readonly source?: TenantSource;
+  /** Header name for `source: "header"`. Default `x-oke-tenant`. */
+  readonly header?: string;
+  /**
+   * Tier-3 escape hatch. When it returns an id, membership is still
+   * checked unless {@link TenantAuthOptions.authoritative} is true.
+   */
+  readonly resolve?: (ctx: TenantResolveContext) => string | null | undefined;
+  /**
+   * When true, {@link TenantAuthOptions.resolve} is trusted without a
+   * membership query. Default false (fail-safe).
+   */
+  readonly authoritative?: boolean;
+}
+
+/** Context passed to {@link TenantAuthOptions.resolve}. */
+export interface TenantResolveContext {
+  readonly auth: {
+    readonly userId: string | null;
+    readonly tenantId?: string | null;
+  };
+  readonly request?: Request;
+  readonly claimTenantId: string | null;
+}
+
+/** Fully resolved tenant auth config. */
+export interface ResolvedTenantAuth {
+  readonly enabled: true;
+  readonly required: boolean;
+  readonly source: TenantSource;
+  readonly header: string;
+  readonly resolve?: TenantAuthOptions["resolve"];
+  readonly authoritative: boolean;
+}
+
+/**
+ * Normalize `gate.auth.tenant`.
+ *
+ * @param input - `true` or options bag
+ */
+export function resolveTenantAuth(input: true | TenantAuthOptions): ResolvedTenantAuth {
+  if (input === true) {
+    return {
+      enabled: true,
+      required: false,
+      source: "claim",
+      header: "x-oke-tenant",
+      authoritative: false,
+    };
+  }
+  return {
+    enabled: true,
+    required: input.required === true,
+    source: input.source ?? "claim",
+    header: input.header ?? "x-oke-tenant",
+    ...(input.resolve !== undefined ? { resolve: input.resolve } : {}),
+    authoritative: input.authoritative === true,
+  };
+}

package/src/auth/tenant-tables.ts

@@ -0,0 +1,11 @@
+/**
+ * Tenant registry table names — kept off AUTH_TABLES so Store-only graphs
+ * that already ship `oke_api_keys` do not also pin `oke_tenants`.
+ */
+
+/** Opt-in via `gate.auth.tenant`. */
+export const AUTH_TENANT_TABLES = {
+  tenants: "oke_tenants",
+  tenantMembers: "oke_tenant_members",
+  tenantRoles: "oke_tenant_roles",
+} as const;

package/src/auth/tenants.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Tenant registry — user-plane catalog on write; membership helpers.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { isApplicationScope } from "../elements/gate/permissions.ts";
+import {
+  createTenant,
+  createTenantStore,
+  tenantRoleScopeFailure,
+  upsertTenantRole,
+} from "./tenants.ts";
+
+describe("tenantRoleScopeFailure", () => {
+  const catalog = ["booking:create", "member", "console:store.sql:write", "console:*"];
+
+  test("unknown names and console:* fail the same way", () => {
+    const invented = tenantRoleScopeFailure(["this:was:never:declared"], catalog);
+    const consoleWrite = tenantRoleScopeFailure(["console:store.sql:write"], catalog);
+    const consoleStar = tenantRoleScopeFailure(["console:*"], catalog);
+    expect(invented?.reason).toBe("unknown_scope");
+    expect(consoleWrite?.reason).toBe("unknown_scope");
+    expect(consoleStar?.reason).toBe("unknown_scope");
+    expect(isApplicationScope("console:store.sql:write")).toBe(false);
+    expect(isApplicationScope("console:*")).toBe(false);
+  });
+
+  test("application catalog names are grantable", () => {
+    expect(tenantRoleScopeFailure(["booking:create", "member"], catalog)).toBeNull();
+  });
+});
+
+describe("upsertTenantRole", () => {
+  test("console-shaped upsert throws like an invented name", async () => {
+    const store = createTenantStore();
+    await createTenant(store, { name: "Acme", createdBy: "u1", id: "t1" });
+    const catalog = ["booking:create", "console:store.sql:write", "console:*"];
+    expect(() =>
+      upsertTenantRole(store, {
+        tenantId: "t1",
+        roleName: "admin",
+        scopes: ["console:store.sql:write"],
+        catalog,
+      }),
+    ).toThrow(/unknown or operator-plane scope/);
+    expect(() =>
+      upsertTenantRole(store, {
+        tenantId: "t1",
+        roleName: "admin",
+        scopes: ["console:*"],
+        catalog,
+      }),
+    ).toThrow(/unknown or operator-plane scope/);
+    expect(() =>
+      upsertTenantRole(store, {
+        tenantId: "t1",
+        roleName: "admin",
+        scopes: ["this:was:never:declared"],
+        catalog,
+      }),
+    ).toThrow(/unknown or operator-plane scope/);
+  });
+});