@celilo/e2e 0.9.2 → 0.10.0

package/registry-server/src/introspection.test.ts

@@ -0,0 +1,247 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { ADMIN_SCOPE } from './auth';
+import {
+  IntrospectionVerifier,
+  claimToScope,
+  introspectionConfigFromEnv,
+} from './introspection';
+
+const CONFIG = {
+  endpoint: 'https://idp.test/application/o/introspect/',
+  clientId: 'celilo-registry',
+  clientSecret: 'super-secret',
+  adminGroup: 'celilo-admins',
+  publisherGroup: 'celilo-authors',
+};
+
+/** Replace global fetch with a stub returning `body` at `status`; restore after. */
+function stubFetch(handler: (url: string, init: RequestInit) => Response): void {
+  // @ts-expect-error - overriding the global for the duration of a test
+  globalThis.fetch = async (url: string | URL | Request, init?: RequestInit) =>
+    handler(String(url), init ?? {});
+}
+
+const realFetch = globalThis.fetch;
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+function introspectResponse(payload: unknown, status = 200): Response {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+describe('claimToScope', () => {
+  test('admin-group member → ADMIN_SCOPE', () => {
+    expect(claimToScope({ active: true, groups: ['celilo-admins'] }, 'celilo-admins')).toBe(
+      ADMIN_SCOPE,
+    );
+  });
+
+  test('non-admin identity → null (owner table is ce-1ch)', () => {
+    expect(claimToScope({ active: true, groups: ['users'] }, 'celilo-admins')).toBeNull();
+    expect(claimToScope({ active: true }, 'celilo-admins')).toBeNull();
+  });
+});
+
+describe('introspectionConfigFromEnv', () => {
+  const KEYS = [
+    'OIDC_INTROSPECTION_ENDPOINT',
+    'OIDC_CLIENT_ID',
+    'OIDC_CLIENT_SECRET',
+    'REGISTRY_ADMIN_GROUP',
+    'REGISTRY_PUBLISHER_GROUP',
+  ];
+  afterEach(() => {
+    for (const k of KEYS) delete process.env[k];
+  });
+
+  test('null when any required var is missing', () => {
+    expect(introspectionConfigFromEnv()).toBeNull();
+    process.env.OIDC_INTROSPECTION_ENDPOINT = 'https://idp.test/introspect/';
+    process.env.OIDC_CLIENT_ID = 'cid';
+    // secret still missing
+    expect(introspectionConfigFromEnv()).toBeNull();
+  });
+
+  test('config when all required vars present; admin group defaults', () => {
+    process.env.OIDC_INTROSPECTION_ENDPOINT = 'https://idp.test/introspect/';
+    process.env.OIDC_CLIENT_ID = 'cid';
+    process.env.OIDC_CLIENT_SECRET = 'sec';
+    expect(introspectionConfigFromEnv()).toEqual({
+      endpoint: 'https://idp.test/introspect/',
+      clientId: 'cid',
+      clientSecret: 'sec',
+      adminGroup: 'celilo-admins',
+      publisherGroup: 'celilo-authors',
+    });
+    process.env.REGISTRY_ADMIN_GROUP = 'ops';
+    expect(introspectionConfigFromEnv()?.adminGroup).toBe('ops');
+    process.env.REGISTRY_PUBLISHER_GROUP = 'authors';
+    expect(introspectionConfigFromEnv()?.publisherGroup).toBe('authors');
+  });
+});
+
+describe('IntrospectionVerifier.scopeOf', () => {
+  const verifier = new IntrospectionVerifier(CONFIG);
+
+  test('active admin-group token → ADMIN_SCOPE', async () => {
+    stubFetch(() =>
+      introspectResponse({ active: true, sub: 'alice', groups: ['celilo-admins'] }),
+    );
+    expect(await verifier.scopeOf('Bearer idp-token')).toBe(ADMIN_SCOPE);
+  });
+
+  test('active non-admin token → null', async () => {
+    stubFetch(() => introspectResponse({ active: true, sub: 'bob', groups: ['users'] }));
+    expect(await verifier.scopeOf('idp-token')).toBeNull();
+  });
+
+  test('active:false → null (revoked at idp)', async () => {
+    stubFetch(() => introspectResponse({ active: false }));
+    expect(await verifier.scopeOf('idp-token')).toBeNull();
+  });
+
+  test('expired exp → null even if active', async () => {
+    const pastSec = Math.floor(Date.now() / 1000) - 60;
+    stubFetch(() =>
+      introspectResponse({ active: true, groups: ['celilo-admins'], exp: pastSec }),
+    );
+    expect(await verifier.scopeOf('idp-token')).toBeNull();
+  });
+
+  test('future exp → honored', async () => {
+    const futureSec = Math.floor(Date.now() / 1000) + 3600;
+    stubFetch(() =>
+      introspectResponse({ active: true, groups: ['celilo-admins'], exp: futureSec }),
+    );
+    expect(await verifier.scopeOf('idp-token')).toBe(ADMIN_SCOPE);
+  });
+
+  test('non-2xx response → null (fail closed)', async () => {
+    stubFetch(() => introspectResponse({ error: 'boom' }, 500));
+    expect(await verifier.scopeOf('idp-token')).toBeNull();
+  });
+
+  test('fetch throws → null (fail closed)', async () => {
+    stubFetch(() => {
+      throw new Error('connection refused');
+    });
+    expect(await verifier.scopeOf('idp-token')).toBeNull();
+  });
+
+  test('malformed body (no active field) → null', async () => {
+    stubFetch(() => introspectResponse({ sub: 'alice' }));
+    expect(await verifier.scopeOf('idp-token')).toBeNull();
+  });
+
+  test('empty header → null without calling the idp', async () => {
+    let called = false;
+    stubFetch(() => {
+      called = true;
+      return introspectResponse({ active: true, groups: ['celilo-admins'] });
+    });
+    expect(await verifier.scopeOf('')).toBeNull();
+    expect(called).toBe(false);
+  });
+
+  test('authenticates with HTTP Basic client creds; sends the token in the body', async () => {
+    let seenAuth = '';
+    let seenBody = '';
+    stubFetch((_url, init) => {
+      seenAuth = new Headers(init.headers).get('Authorization') ?? '';
+      seenBody = String(init.body ?? '');
+      return introspectResponse({ active: true, groups: ['celilo-admins'] });
+    });
+    await verifier.scopeOf('Bearer the-token');
+    const expected = `Basic ${Buffer.from('celilo-registry:super-secret').toString('base64')}`;
+    expect(seenAuth).toBe(expected);
+    expect(seenBody).toContain('token=the-token');
+  });
+
+  test('does not log the token or client secret on failure', async () => {
+    const logs: string[] = [];
+    const realErr = console.error;
+    console.error = (...args: unknown[]) => {
+      logs.push(args.map(String).join(' '));
+    };
+    try {
+      stubFetch(() => {
+        throw new Error('boom');
+      });
+      await verifier.scopeOf('Bearer top-secret-token');
+    } finally {
+      console.error = realErr;
+    }
+    const joined = logs.join('\n');
+    expect(joined).not.toContain('top-secret-token');
+    expect(joined).not.toContain('super-secret');
+  });
+});
+
+describe('IntrospectionVerifier.identify (ce-1ch)', () => {
+  const verifier = new IntrospectionVerifier(CONFIG);
+
+  test('admin-group member → isAdmin, group=adminGroup', async () => {
+    stubFetch(() => introspectResponse({ active: true, sub: 'alice', groups: ['celilo-admins'] }));
+    expect(await verifier.identify('Bearer t')).toEqual({
+      sub: 'alice',
+      isAdmin: true,
+      isPublisher: false,
+      group: 'celilo-admins',
+    });
+  });
+
+  test('publisher-group member → isPublisher, group=publisherGroup', async () => {
+    stubFetch(() => introspectResponse({ active: true, sub: 'bob', groups: ['celilo-authors'] }));
+    expect(await verifier.identify('Bearer t')).toEqual({
+      sub: 'bob',
+      isAdmin: false,
+      isPublisher: true,
+      group: 'celilo-authors',
+    });
+  });
+
+  test('member of neither publish group → verified but no group', async () => {
+    stubFetch(() => introspectResponse({ active: true, sub: 'carol', groups: ['users'] }));
+    expect(await verifier.identify('Bearer t')).toEqual({
+      sub: 'carol',
+      isAdmin: false,
+      isPublisher: false,
+      group: undefined,
+    });
+  });
+
+  test('admin with no sub → identified (admins publish without an ownership anchor)', async () => {
+    stubFetch(() => introspectResponse({ active: true, groups: ['celilo-admins'] }));
+    expect(await verifier.identify('Bearer t')).toEqual({
+      sub: undefined,
+      isAdmin: true,
+      isPublisher: false,
+      group: 'celilo-admins',
+    });
+  });
+
+  test('active:false → null (fail closed)', async () => {
+    stubFetch(() => introspectResponse({ active: false }));
+    expect(await verifier.identify('Bearer t')).toBeNull();
+  });
+
+  test('expired exp → null even if active', async () => {
+    const pastSec = Math.floor(Date.now() / 1000) - 60;
+    stubFetch(() =>
+      introspectResponse({ active: true, sub: 'alice', groups: ['celilo-admins'], exp: pastSec }),
+    );
+    expect(await verifier.identify('Bearer t')).toBeNull();
+  });
+
+  test('admin group is configurable, not a literal', async () => {
+    const custom = new IntrospectionVerifier({ ...CONFIG, adminGroup: 'ops', publisherGroup: 'devs' });
+    stubFetch(() => introspectResponse({ active: true, sub: 'dan', groups: ['ops'] }));
+    const id = await custom.identify('Bearer t');
+    expect(id?.isAdmin).toBe(true);
+    expect(id?.group).toBe('ops');
+  });
+});

package/registry-server/src/introspection.ts

@@ -0,0 +1,204 @@
+import { ADMIN_SCOPE, bearerToken } from './auth';
+
+/**
+ * RFC 7662 token-introspection verify-bridge
+ * (SECURE_MODULE_PUBLISH.md §5[D-A], MODULE_PACKAGE_SIGNING.md Phase 1).
+ *
+ * The registry POSTs a presented publish token to the idp's introspection
+ * endpoint, authenticating with its own confidential OIDC client credentials
+ * (provisioned on install — ce-7aa). It reads back `{active, sub, groups, exp}`
+ * and maps a verified identity to a publish scope the request path already
+ * understands (ADMIN_SCOPE / per-package — see {@link claimToScope}).
+ *
+ * Two properties this module MUST preserve:
+ *   1. **Fail closed.** Any non-2xx response, network error, or malformed body
+ *      denies the token (returns null). The idp being unreachable never
+ *      degrades into "allow".
+ *   2. **No secrets in logs.** The token and client secret are never logged;
+ *      only HTTP status / error class is.
+ */
+
+/** Validated subset of an RFC 7662 introspection response. */
+export interface IntrospectionResult {
+  active: boolean;
+  sub?: string;
+  groups?: string[];
+  exp?: number;
+}
+
+export interface IntrospectionConfig {
+  /** RFC 7662 introspection endpoint (OIDC_INTROSPECTION_ENDPOINT). */
+  endpoint: string;
+  /** Confidential OIDC client id (OIDC_CLIENT_ID). */
+  clientId: string;
+  /** Confidential OIDC client secret (OIDC_CLIENT_SECRET). */
+  clientSecret: string;
+  /** Group whose members map to ADMIN_SCOPE (REGISTRY_ADMIN_GROUP). */
+  adminGroup: string;
+  /**
+   * Group whose members may publish modules they own (REGISTRY_PUBLISHER_GROUP,
+   * ce-1ch). Configurable, not a literal. Members claim/publish per the
+   * module-owner table; admins additionally publish/reassign anything.
+   */
+  publisherGroup: string;
+}
+
+/**
+ * A verified idp identity (ce-1ch). `identify()` resolves an Authorization
+ * header to this via introspection, or null when the token is inactive/expired/
+ * unverifiable or carries no `sub` (ownership requires a stable subject).
+ */
+export interface VerifiedIdentity {
+  /**
+   * Verified subject — the owner key in the module-owner table. Optional: an
+   * admin identity may publish without one (admins need no ownership anchor),
+   * but the publisher/owner path requires it to attribute a claim.
+   */
+  sub?: string;
+  /** Member of the admin group → may publish/reassign any module. */
+  isAdmin: boolean;
+  /** Member of the publisher group → may claim + publish owned modules. */
+  isPublisher: boolean;
+  /**
+   * The group that grants this identity's publish rights (admin group when
+   * admin, else publisher group when publisher, else undefined). Recorded as
+   * the owner entry's `sourceGroup` at claim time.
+   */
+  group?: string;
+}
+
+/** Default admin group name when REGISTRY_ADMIN_GROUP is unset. */
+const DEFAULT_ADMIN_GROUP = 'celilo-admins';
+
+/** Default publisher group name when REGISTRY_PUBLISHER_GROUP is unset. */
+const DEFAULT_PUBLISHER_GROUP = 'celilo-authors';
+
+/**
+ * Read introspection config from the environment (delivered by the module's
+ * OIDC drop-in EnvironmentFile — ce-7aa). Returns null when introspection is
+ * not configured, in which case the server keeps the opaque-token-only path.
+ */
+export function introspectionConfigFromEnv(): IntrospectionConfig | null {
+  const endpoint = process.env.OIDC_INTROSPECTION_ENDPOINT?.trim();
+  const clientId = process.env.OIDC_CLIENT_ID?.trim();
+  const clientSecret = process.env.OIDC_CLIENT_SECRET?.trim();
+  if (!endpoint || !clientId || !clientSecret) return null;
+  return {
+    endpoint,
+    clientId,
+    clientSecret,
+    adminGroup: process.env.REGISTRY_ADMIN_GROUP?.trim() || DEFAULT_ADMIN_GROUP,
+    publisherGroup: process.env.REGISTRY_PUBLISHER_GROUP?.trim() || DEFAULT_PUBLISHER_GROUP,
+  };
+}
+
+/**
+ * Map a verified identity's claims to a publish scope the request path
+ * consumes. Today: membership in the admin group → ADMIN_SCOPE (`*`).
+ *
+ * ponytail: per-module ownership (a verified non-admin identity may publish
+ * only modules it owns) is the module-owner table — ce-1ch — which extends
+ * this seam. Until then a verified non-admin identity is denied (null).
+ */
+export function claimToScope(claims: IntrospectionResult, adminGroup: string): string | null {
+  if (claims.groups?.includes(adminGroup)) return ADMIN_SCOPE;
+  return null;
+}
+
+/** Hand-validate an untrusted introspection JSON body (no zod dep in this package). */
+function parseIntrospection(json: unknown): IntrospectionResult | null {
+  if (typeof json !== 'object' || json === null) return null;
+  const o = json as Record<string, unknown>;
+  if (typeof o.active !== 'boolean') return null;
+  const groups = Array.isArray(o.groups)
+    ? o.groups.filter((g): g is string => typeof g === 'string')
+    : undefined;
+  return {
+    active: o.active,
+    sub: typeof o.sub === 'string' ? o.sub : undefined,
+    groups,
+    exp: typeof o.exp === 'number' ? o.exp : undefined,
+  };
+}
+
+function errClass(error: unknown): string {
+  return error instanceof Error ? error.name : 'unknown';
+}
+
+export class IntrospectionVerifier {
+  constructor(private readonly config: IntrospectionConfig) {}
+
+  /** Construct from env, or undefined when introspection isn't configured. */
+  static fromEnv(): IntrospectionVerifier | undefined {
+    const config = introspectionConfigFromEnv();
+    return config ? new IntrospectionVerifier(config) : undefined;
+  }
+
+  /**
+   * Verify an Authorization header value via introspection and return the
+   * publish scope of the identity (ADMIN_SCOPE / per-package), or null when
+   * the token is inactive, expired, unverifiable, or maps to no scope.
+   * Fails CLOSED on every error.
+   */
+  async scopeOf(header: string): Promise<string | null> {
+    const token = bearerToken(header);
+    if (!token) return null;
+    const claims = await this.introspect(token);
+    if (!claims || !claims.active) return null;
+    // RFC 7662 `active:false` already covers expiry, but double-check `exp`
+    // defensively (seconds since epoch) so a misbehaving idp can't slip an
+    // expired-but-active token past us.
+    if (typeof claims.exp === 'number' && claims.exp * 1000 <= Date.now()) return null;
+    return claimToScope(claims, this.config.adminGroup);
+  }
+
+  /**
+   * Verify an Authorization header and resolve the caller's identity for the
+   * hybrid group + owner-table authorization (ce-1ch). Returns null on the same
+   * fail-closed conditions as {@link scopeOf}. `sub` may be absent (an admin can
+   * publish without one); the owner path in the server requires it and denies
+   * a publisher identity that lacks it.
+   */
+  async identify(header: string): Promise<VerifiedIdentity | null> {
+    const token = bearerToken(header);
+    if (!token) return null;
+    const claims = await this.introspect(token);
+    if (!claims || !claims.active) return null;
+    if (typeof claims.exp === 'number' && claims.exp * 1000 <= Date.now()) return null;
+    const isAdmin = claims.groups?.includes(this.config.adminGroup) ?? false;
+    const isPublisher = claims.groups?.includes(this.config.publisherGroup) ?? false;
+    const group = isAdmin
+      ? this.config.adminGroup
+      : isPublisher
+        ? this.config.publisherGroup
+        : undefined;
+    return { sub: claims.sub, isAdmin, isPublisher, group };
+  }
+
+  private async introspect(token: string): Promise<IntrospectionResult | null> {
+    try {
+      const basic = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString(
+        'base64',
+      );
+      const resp = await fetch(this.config.endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          Authorization: `Basic ${basic}`,
+          Accept: 'application/json',
+        },
+        body: new URLSearchParams({ token, token_type_hint: 'access_token' }).toString(),
+      });
+      if (!resp.ok) {
+        console.error(`[registry] introspection HTTP ${resp.status} — denying (fail closed)`);
+        return null;
+      }
+      return parseIntrospection(await resp.json());
+    } catch (error) {
+      console.error(
+        `[registry] introspection request failed (${errClass(error)}) — denying (fail closed)`,
+      );
+      return null;
+    }
+  }
+}

package/registry-server/src/module-owner-store.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  type ModuleOwnerEntry,
+  type ModuleOwnerPersistence,
+  ModuleOwnerStore,
+} from './module-owner-store';
+
+/** In-memory persistence seam so the store is testable without the filesystem. */
+function memPersistence(initial: ModuleOwnerEntry[] = []): ModuleOwnerPersistence & {
+  saved: ModuleOwnerEntry[];
+} {
+  const state = { saved: [...initial] };
+  return {
+    saved: state.saved,
+    load: () => [...state.saved],
+    save(entries) {
+      state.saved.length = 0;
+      state.saved.push(...entries);
+    },
+  };
+}
+
+const fixedNow = () => '2026-01-01T00:00:00.000Z';
+
+describe('ModuleOwnerStore', () => {
+  test('claim records ownership of an unclaimed name', () => {
+    const p = memPersistence();
+    const store = new ModuleOwnerStore(p, fixedNow);
+    const entry = store.claim('homebridge', 'alice', 'celilo-authors');
+    expect(entry).toEqual({
+      moduleName: 'homebridge',
+      ownerSub: 'alice',
+      claimedAt: fixedNow(),
+      sourceGroup: 'celilo-authors',
+    });
+    expect(store.get('homebridge')?.ownerSub).toBe('alice');
+    expect(p.saved).toHaveLength(1);
+  });
+
+  test('claim never steals an already-owned name (returns existing)', () => {
+    const store = new ModuleOwnerStore(memPersistence(), fixedNow);
+    store.claim('homebridge', 'alice', 'celilo-authors');
+    const second = store.claim('homebridge', 'bob', 'celilo-authors');
+    expect(second.ownerSub).toBe('alice');
+    expect(store.get('homebridge')?.ownerSub).toBe('alice');
+  });
+
+  test('reassign overwrites an existing owner (admin path)', () => {
+    const store = new ModuleOwnerStore(memPersistence(), fixedNow);
+    store.claim('homebridge', 'alice', 'celilo-authors');
+    const reassigned = store.reassign('homebridge', 'bob', 'admin-reassign');
+    expect(reassigned.ownerSub).toBe('bob');
+    expect(store.get('homebridge')?.ownerSub).toBe('bob');
+    // No duplicate rows for the same name.
+    expect(store.list().filter((e) => e.moduleName === 'homebridge')).toHaveLength(1);
+  });
+
+  test('reassign creates a record when the name was unclaimed', () => {
+    const store = new ModuleOwnerStore(memPersistence(), fixedNow);
+    store.reassign('caddy', 'carol', 'admin-reassign');
+    expect(store.get('caddy')?.ownerSub).toBe('carol');
+  });
+
+  test('get returns undefined for an unclaimed name', () => {
+    const store = new ModuleOwnerStore(memPersistence(), fixedNow);
+    expect(store.get('nope')).toBeUndefined();
+  });
+
+  test('loads persisted entries on construction', () => {
+    const p = memPersistence([
+      { moduleName: 'caddy', ownerSub: 'dan', claimedAt: fixedNow(), sourceGroup: 'celilo-admins' },
+    ]);
+    const store = new ModuleOwnerStore(p, fixedNow);
+    expect(store.get('caddy')?.ownerSub).toBe('dan');
+    expect(store.list()).toHaveLength(1);
+  });
+
+  test('list returns a copy (mutating it does not affect the store)', () => {
+    const store = new ModuleOwnerStore(memPersistence(), fixedNow);
+    store.claim('a', 'x', 'g');
+    const list = store.list();
+    list.pop();
+    expect(store.list()).toHaveLength(1);
+  });
+});

package/registry-server/src/module-owner-store.ts

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Persisted module-owner table (SECURE_MODULE_PUBLISH.md §5[D-C], ce-1ch).
+ *
+ * The introspection verify-bridge (ce-s7e) proves *who* a publish token belongs
+ * to (a verified `sub` + group claims). This table gates *which modules* that
+ * identity may publish: a module name is **first-publish-claims** — the first
+ * verified publisher of an unclaimed name records ownership; thereafter only the
+ * owner (or an admin) may publish it. This defends the confused-deputy case:
+ * Author-A holding a valid idp token cannot publish Author-B's module.
+ *
+ * Ownership is low-friction / npm-style: no pre-registration, admin can reassign.
+ * Mirrors {@link ScopedTokenStore} (JSON file + I/O seam for unit testing).
+ */
+
+export interface ModuleOwnerEntry {
+  /** Module name this ownership record governs. */
+  moduleName: string;
+  /** Verified idp subject that owns the name (from introspection `sub`). */
+  ownerSub: string;
+  /** ISO timestamp the name was first claimed. */
+  claimedAt: string;
+  /** Group claim that granted the claim (admin or publisher group at claim time). */
+  sourceGroup: string;
+}
+
+/** I/O seam (Rule 2.3) so the store is unit-testable without the filesystem. */
+export interface ModuleOwnerPersistence {
+  load(): ModuleOwnerEntry[];
+  save(entries: ModuleOwnerEntry[]): void;
+}
+
+/** File-backed persistence: a JSON array at `filePath`, tolerant of a missing file. */
+export function fileModuleOwnerPersistence(filePath: string): ModuleOwnerPersistence {
+  return {
+    load() {
+      if (!existsSync(filePath)) return [];
+      try {
+        const parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+        return Array.isArray(parsed) ? (parsed as ModuleOwnerEntry[]) : [];
+      } catch {
+        return [];
+      }
+    },
+    save(entries) {
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, JSON.stringify(entries, null, 2));
+    },
+  };
+}
+
+export class ModuleOwnerStore {
+  private entries: ModuleOwnerEntry[];
+
+  constructor(
+    private readonly persistence: ModuleOwnerPersistence,
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {
+    this.entries = persistence.load();
+  }
+
+  list(): ModuleOwnerEntry[] {
+    return [...this.entries];
+  }
+
+  /** The ownership record for `moduleName`, or undefined when unclaimed. */
+  get(moduleName: string): ModuleOwnerEntry | undefined {
+    return this.entries.find((e) => e.moduleName === moduleName);
+  }
+
+  /**
+   * Record ownership of an **unclaimed** name for `ownerSub`. If the name is
+   * already claimed this is a no-op and returns the *existing* entry — claiming
+   * never steals a name (use {@link reassign} for admin overwrite). Returns the
+   * effective owner entry either way.
+   */
+  claim(moduleName: string, ownerSub: string, sourceGroup: string): ModuleOwnerEntry {
+    const existing = this.get(moduleName);
+    if (existing) return existing;
+    const entry: ModuleOwnerEntry = {
+      moduleName,
+      ownerSub,
+      claimedAt: this.now(),
+      sourceGroup,
+    };
+    this.entries = [...this.entries, entry];
+    this.persistence.save(this.entries);
+    return entry;
+  }
+
+  /**
+   * Overwrite (or create) the ownership record for `moduleName` — admin
+   * reassignment. Unlike {@link claim} this steals an already-owned name.
+   */
+  reassign(moduleName: string, ownerSub: string, sourceGroup: string): ModuleOwnerEntry {
+    const entry: ModuleOwnerEntry = {
+      moduleName,
+      ownerSub,
+      claimedAt: this.now(),
+      sourceGroup,
+    };
+    this.entries = [...this.entries.filter((e) => e.moduleName !== moduleName), entry];
+    this.persistence.save(this.entries);
+    return entry;
+  }
+}