@openlup/platform 0.0.0 → 0.16.0

package/src/identity/oidcIdentityVerifier.ts

@@ -0,0 +1,229 @@
+import type { IdentityJwtLibrary, IdentityJwtLibraryLoader, IdentityJwk } from "./jwtLibrary.js";
+import type { IdentityVerifierPort, VerifiedPrincipal } from "./ports.js";
+import type { OidcFailureCode } from "./contracts/oidc.js";
+import { deriveOidcPrincipalId } from "./oidcPrincipal.js";
+
+export interface OidcIdentityVerifierConfig {
+  issuer: string;
+  audience: string;
+  algorithms: readonly ("RS256" | "ES256")[];
+  maxTokenLifetimeSeconds: number;
+  requireSingleAudience?: boolean;
+  /** Conformance only: literal loopback addresses, never arbitrary HTTP hosts. */
+  allowLoopbackHttp?: boolean;
+}
+export type OidcVerificationResult = { ok: true; principal: VerifiedPrincipal; expiresAt: string }
+  | { ok: false; code: OidcFailureCode };
+export interface OidcReadinessReport {
+  state: "ready" | "unknown" | "unsatisfied";
+  discovery: { reachable: boolean; valid: boolean; checkedAt: string | null; expiresAt: string | null };
+  jwks: { loaded: boolean; checkedAt: string | null; expiresAt: string | null };
+  code?: OidcFailureCode;
+}
+export interface OidcIdentityVerifier extends IdentityVerifierPort {
+  verifyToken(token: string): Promise<OidcVerificationResult>;
+  readiness(): Promise<OidcReadinessReport>;
+}
+class Refusal extends Error {
+  constructor(readonly code: OidcFailureCode) { super(code); }
+}
+const refuse = (code: OidcFailureCode): never => { throw new Refusal(code); };
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const bounded = (value: unknown, max: number): value is string => typeof value === "string" && value.length > 0 && Buffer.byteLength(value) <= max && !Array.from(value).some(character => character.charCodeAt(0) <= 0x20 || character.charCodeAt(0) === 0x7f);
+const stamp = (value: number | null) => value === null ? null : new Date(value).toISOString();
+const unavailable = (code: OidcFailureCode) => code.endsWith("_UNAVAILABLE") || code === "OIDC_JWKS_REFRESH_RATE_LIMITED";
+
+/** One binding per host/configuration. Imports and construction perform no I/O or JWT loading. */
+export function createOidcIdentityVerifier(config: OidcIdentityVerifierConfig, dependencies: {
+  loadJwt: IdentityJwtLibraryLoader; fetch?: typeof globalThis.fetch; now?: () => number;
+}): OidcIdentityVerifier {
+  const settings = { ...config, algorithms: [...config.algorithms] };
+  const now = dependencies.now ?? Date.now;
+  const transport = dependencies.fetch ?? globalThis.fetch;
+  function validUrl(value: string) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash || (url.protocol !== "https:"
+      && !(settings.allowLoopbackHttp && url.protocol === "http:" && ["127.0.0.1", "[::1]"].includes(url.hostname)))) throw new Error();
+    return url;
+  }
+  let origin = "", configurationValid = true;
+  try {
+    if (!bounded(settings.issuer, 2048) || !bounded(settings.audience, 256)
+      || !settings.algorithms.length || settings.algorithms.some(alg => alg !== "RS256" && alg !== "ES256")
+      || !Number.isInteger(settings.maxTokenLifetimeSeconds) || settings.maxTokenLifetimeSeconds < 1 || settings.maxTokenLifetimeSeconds > 3600) throw new Error();
+    origin = validUrl(settings.issuer).origin;
+  } catch { configurationValid = false; }
+  let library: Promise<IdentityJwtLibrary> | undefined;
+  const jwt = () => library ??= Promise.resolve().then(dependencies.loadJwt).catch(() => { library = undefined; return refuse("OIDC_JWT_LIBRARY_UNAVAILABLE"); });
+  let discovery: { jwksUrl: string; expires: number } | undefined;
+  let keys: { values: IdentityJwk[]; expires: number } | undefined;
+  let discoveryCheck: number | null = null, keyCheck: number | null = null, lastKeyAttempt = -Infinity;
+  let reachable = false, discoveryValid = false;
+  let discoveryFlight: Promise<NonNullable<typeof discovery>> | undefined;
+  let keyFlight: Promise<NonNullable<typeof keys>> | undefined;
+  let keyFailure: OidcFailureCode | undefined;
+
+  async function document(url: string, kind: "DISCOVERY" | "JWKS", maxAge: number) {
+    const controller = new AbortController();
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<never>((_, reject) => { timer = setTimeout(() => {
+      controller.abort(); void reader?.cancel().catch(() => {});
+      reject(new Refusal(`OIDC_${kind}_UNAVAILABLE`));
+    }, 3000); });
+    try {
+      return await Promise.race([deadline, (async () => {
+        const response = await transport(url, { redirect: "error", signal: controller.signal, headers: { accept: "application/json" } });
+        if (kind === "DISCOVERY") reachable = true;
+        if (!response.ok) return refuse(`OIDC_${kind}_UNAVAILABLE`);
+        if (response.redirected || (response.url && response.url !== url)) return refuse(`OIDC_${kind}_INVALID`);
+        const length = response.headers.get("content-length");
+        if (length && (!/^\d+$/.test(length) || Number(length) > 65536)) return refuse(`OIDC_${kind}_INVALID`);
+        if (!response.body) return refuse(`OIDC_${kind}_INVALID`);
+        reader = response.body.getReader();
+        const chunks: Uint8Array[] = []; let size = 0;
+        for (;;) {
+          const part = await reader.read(); if (part.done) break;
+          size += part.value.byteLength;
+          if (size > 65536) { void reader.cancel().catch(() => {}); return refuse(`OIDC_${kind}_INVALID`); }
+          chunks.push(part.value);
+        }
+        let value: unknown;
+        try { value = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { return refuse(`OIDC_${kind}_INVALID`); }
+        const control = response.headers.get("cache-control") ?? "";
+        const ages = [...control.matchAll(/(?:^|,)\s*max-age\s*=\s*"?(\d+)"?/gi)].map(match => Number(match[1]));
+        const age = Number(response.headers.get("age") ?? "0");
+        // Revalidate no-cache documents at the next permitted JWKS refresh.
+        const cacheBound = /(?:^|,)\s*no-cache(?:\s|,|$)/i.test(control) ? 30 : maxAge;
+        const seconds = /(?:^|,)\s*no-store(?:\s|,|$)/i.test(control) ? 0
+          : Math.max(0, Math.min(maxAge, cacheBound, ...ages) - (Number.isFinite(age) && age >= 0 ? age : maxAge));
+        return { value, expires: now() + seconds * 1000 };
+      })()]);
+    } catch (error) {
+      if (error instanceof Refusal) throw error;
+      return refuse(`OIDC_${kind}_UNAVAILABLE`);
+    } finally { clearTimeout(timer); controller.abort(); }
+  }
+  async function metadata() {
+    if (!configurationValid) return refuse("OIDC_CONFIGURATION_INVALID");
+    if (discovery && discovery.expires > now()) return discovery;
+    if (discoveryFlight) return discoveryFlight;
+    discoveryFlight = (async () => {
+      discoveryCheck = now(); reachable = false; discoveryValid = false;
+      const fetched = await document(`${settings.issuer.replace(/\/$/, "")}/.well-known/openid-configuration`, "DISCOVERY", 3600);
+      if (!record(fetched.value) || fetched.value.issuer !== settings.issuer || typeof fetched.value.jwks_uri !== "string") return refuse("OIDC_DISCOVERY_INVALID");
+      try { if (validUrl(fetched.value.jwks_uri).origin !== origin) throw new Error(); }
+      catch { return refuse("OIDC_DISCOVERY_INVALID"); }
+      if (discovery?.jwksUrl !== fetched.value.jwks_uri) keys = undefined;
+      discoveryValid = true;
+      return discovery = { jwksUrl: fetched.value.jwks_uri, expires: fetched.expires };
+    })();
+    try { return await discoveryFlight; } finally { discoveryFlight = undefined; }
+  }
+  async function keySet(force = false) {
+    const meta = await metadata();
+    if (!force && keys && keys.expires > now()) return keys;
+    if (keyFlight) return keyFlight;
+    if (now() - lastKeyAttempt < 30000) return refuse("OIDC_JWKS_REFRESH_RATE_LIMITED");
+    lastKeyAttempt = now(); keyCheck = now();
+    keyFlight = (async () => {
+      const fetched = await document(meta.jwksUrl, "JWKS", 300);
+      const value = fetched.value;
+      if (!record(value) || !Array.isArray(value.keys) || !value.keys.length || value.keys.length > 64) return refuse("OIDC_JWKS_INVALID");
+      const eligible: IdentityJwk[] = [];
+      for (const key of value.keys) {
+        if (!record(key) || ["d", "p", "q", "dp", "dq", "qi", "oth", "k"].some(field => field in key)) return refuse("OIDC_JWKS_INVALID");
+        if ((key.use !== undefined && key.use !== "sig") || (key.key_ops !== undefined && (!Array.isArray(key.key_ops) || !key.key_ops.length || !key.key_ops.every(operation => operation === "verify")))) continue;
+        const alg = key.alg === undefined ? (key.kty === "RSA" ? "RS256" : key.kty === "EC" && key.crv === "P-256" ? "ES256" : "") : key.alg;
+        if (!settings.algorithms.includes(alg as "RS256" | "ES256")
+          || (alg === "RS256" ? key.kty !== "RSA" : key.kty !== "EC" || key.crv !== "P-256")) continue;
+        if (!bounded(key.kid, 128) || (alg === "RS256" ? !bounded(key.n, 2048) || !bounded(key.e, 16)
+          : !bounded(key.x, 128) || !bounded(key.y, 128))) return refuse("OIDC_JWKS_INVALID");
+        eligible.push({ ...key, alg: String(alg) });
+      }
+      if (!eligible.length || new Set(eligible.map(key => key.kid)).size !== eligible.length) return refuse("OIDC_JWKS_INVALID");
+      const lib = await jwt();
+      try { await Promise.all(eligible.map(key => lib.importJWK(key, key.alg!))); }
+      catch { return refuse("OIDC_JWKS_INVALID"); }
+      keyFailure = undefined;
+      return keys = { values: eligible, expires: fetched.expires };
+    })();
+    try { return await keyFlight; }
+    catch (error) { keyFailure = error instanceof Refusal ? error.code : "OIDC_JWKS_UNAVAILABLE"; throw error; }
+    finally { keyFlight = undefined; }
+  }
+  async function verifyToken(token: string): Promise<OidcVerificationResult> {
+    try {
+      if (!configurationValid) return refuse("OIDC_CONFIGURATION_INVALID");
+      if (typeof token !== "string" || Buffer.byteLength(token) > 16384 || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token)) return refuse("OIDC_TOKEN_INVALID");
+      let header: unknown, unverifiedPayload: unknown;
+      try {
+        const parts = token.split(".").map(part => {
+          const bytes = Buffer.from(part, "base64url");
+          if (bytes.toString("base64url") !== part) return refuse("OIDC_TOKEN_INVALID");
+          return bytes;
+        });
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        header = JSON.parse(decoder.decode(parts[0]!));
+        unverifiedPayload = JSON.parse(decoder.decode(parts[1]!));
+      } catch { return refuse("OIDC_TOKEN_INVALID"); }
+      if (!record(header) || !record(unverifiedPayload) || !bounded(header.kid, 128)
+        || !settings.algorithms.includes(header.alg as "RS256" | "ES256")) return refuse("OIDC_TOKEN_INVALID");
+      // Unverified claims may refuse before I/O; only verified claims can admit.
+      if (unverifiedPayload.iss !== settings.issuer) return refuse("OIDC_ISSUER_MISMATCH");
+      let set = await keySet();
+      const select = () => set.values.find(key => key.kid === header.kid && key.alg === header.alg);
+      if (!select()) { set = await keySet(true); if (!select()) return refuse("OIDC_KID_UNKNOWN"); }
+      const lib = await jwt();
+      const selected = select()!;
+      let payload;
+      try {
+        const key = await lib.importJWK(selected, String(header.alg));
+        ({ payload } = await lib.jwtVerify(token, async protectedHeader => {
+          if (protectedHeader.alg !== header.alg || protectedHeader.kid !== header.kid) return refuse("OIDC_TOKEN_INVALID");
+          return key;
+        }, { algorithms: settings.algorithms, audience: settings.audience, issuer: settings.issuer, currentDate: new Date(now()), clockTolerance: 0 }));
+      } catch (error) {
+        if (record(error)) {
+          if (error.code === "ERR_JWT_EXPIRED") return refuse("OIDC_TOKEN_EXPIRED");
+          if (error.code === "ERR_JWT_CLAIM_VALIDATION_FAILED") {
+            if (error.claim === "iss") return refuse("OIDC_ISSUER_MISMATCH");
+            if (error.claim === "aud") return refuse("OIDC_AUDIENCE_MISMATCH");
+            if (error.claim === "nbf") return refuse("OIDC_TOKEN_NOT_ACTIVE");
+          }
+        }
+        return refuse("OIDC_TOKEN_INVALID");
+      }
+      if (payload.iss !== settings.issuer) return refuse("OIDC_ISSUER_MISMATCH");
+      if (settings.requireSingleAudience ? payload.aud !== settings.audience
+        : !(payload.aud === settings.audience || (Array.isArray(payload.aud) && payload.aud.every(aud => typeof aud === "string") && payload.aud.includes(settings.audience)))) return refuse("OIDC_AUDIENCE_MISMATCH");
+      const seconds = now() / 1000;
+      if (!Number.isSafeInteger(payload.iat) || !Number.isSafeInteger(payload.exp) || payload.exp! <= payload.iat!
+        || payload.exp! - payload.iat! > settings.maxTokenLifetimeSeconds || payload.iat! > seconds) return refuse("OIDC_TOKEN_LIFETIME_INVALID");
+      if (payload.exp! <= seconds) return refuse("OIDC_TOKEN_EXPIRED");
+      if (payload.nbf !== undefined && (!Number.isSafeInteger(payload.nbf) || payload.nbf > seconds)) return refuse("OIDC_TOKEN_NOT_ACTIVE");
+      if (!bounded(payload.sub, 1024)) return refuse("OIDC_SUBJECT_INVALID");
+      if (!bounded(payload.email, 254) || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(payload.email)) return refuse("OIDC_EMAIL_INVALID");
+      if (payload.email_verified !== true) return refuse("OIDC_EMAIL_UNVERIFIED");
+      return { ok: true, principal: { principalId: deriveOidcPrincipalId(settings.issuer, payload.sub), email: payload.email.trim().toLowerCase(), emailVerified: true }, expiresAt: stamp(payload.exp! * 1000)! };
+    } catch (error) { return { ok: false, code: error instanceof Refusal ? error.code : "OIDC_TOKEN_INVALID" }; }
+  }
+  return {
+    verifyToken,
+    async verifyAccessToken(token) {
+      const result = await verifyToken(token);
+      if (result.ok) return result.principal;
+      if (unavailable(result.code)) throw new Error("OIDC identity verification unavailable");
+      return null;
+    },
+    async readiness() {
+      let code: OidcFailureCode | undefined;
+      try { await keySet(); } catch (error) { code = error instanceof Refusal ? error.code : "OIDC_JWKS_UNAVAILABLE"; }
+      if (code === "OIDC_JWKS_REFRESH_RATE_LIMITED" && keyFailure) code = keyFailure;
+      const fresh = !!keys && keys.expires > now();
+      return { state: code ? unavailable(code) ? "unknown" : "unsatisfied" : fresh ? "ready" : "unsatisfied",
+        discovery: { reachable, valid: discoveryValid && !!discovery && discovery.expires > now(), checkedAt: stamp(discoveryCheck), expiresAt: stamp(discovery?.expires ?? null) },
+        jwks: { loaded: fresh, checkedAt: stamp(keyCheck), expiresAt: stamp(keys?.expires ?? null) }, ...(code ? { code } : {}) };
+    },
+  };
+}

package/src/identity/oidcPrincipal.ts

@@ -0,0 +1,10 @@
+import { createHash } from "node:crypto";
+/** Frozen UTF-8, domain-separated SHA-256 UUIDv8 mapping of the exact issuer/subject pair. */
+export function deriveOidcPrincipalId(issuer: string, subject: string): string {
+  const bytes = createHash("sha256").update("openlup:oidc-principal:v1\0", "utf8")
+    .update(JSON.stringify([issuer, subject]), "utf8").digest().subarray(0, 16);
+  bytes[6] = (bytes[6]! & 0x0f) | 0x80;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/identity/operatorAdminAuth.ts

@@ -0,0 +1,14 @@
+import type { AdminAuthPort, IdentityVerifierPort } from "./ports.js";
+import type { OperatorIdentityStore } from "./operatorPorts.js";
+export function createOperatorAdminAuth(options: { verifier: IdentityVerifierPort; authority: Pick<OperatorIdentityStore, "findMembership"> }): AdminAuthPort {
+  return { async authorize(token, restrictions) {
+    const principal = token ? await options.verifier.verifyAccessToken(token) : null;
+    if (!principal) return { ok: false, code: "UNAUTHORIZED", message: "Operator authentication required" };
+    const member = await options.authority.findMembership(principal.principalId);
+    if (!member || member.membershipState !== "active" || (member.role !== "admin" && member.role !== "distributor")
+      || (restrictions?.allowedRoles && !restrictions.allowedRoles.includes(member.role))) {
+      return { ok: false, code: "FORBIDDEN", message: "Operator access denied" };
+    }
+    return { ok: true, principalId: principal.principalId, role: member.role, isMachineActor: false };
+  } };
+}

package/src/identity/operatorAuthHandlers.ts

@@ -0,0 +1,52 @@
+import { operatorChallengeRequestSchema, operatorChallengeVerificationSchema, operatorSessionSchema } from "./contracts/operatorAuth.js";
+import { createMagicLinkOriginResolver } from "./authVerifyUrl.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { createOperatorSessionService } from "./operatorSession.js";
+export interface OperatorAuthMessages { invalidRequest: string; forbidden: string; unauthorized: string; unavailable: string }
+export function createOperatorAuthHandlers(options: IdentityResponseOptions & {
+  sessions: ReturnType<typeof createOperatorSessionService>; origin: string; messages: OperatorAuthMessages;
+  padResponseTime(startedAt: number, minimumMs: number): Promise<void>;
+}) {
+  const responder = createIdentityResponder(options);
+  const origin = createMagicLinkOriginResolver([options.origin]);
+  function admitted(req: HttpRequest, res: HttpResponse): boolean {
+    if (req.method !== "POST") { responder.sendMethodNotAllowed(res, ["POST"]); return false; }
+    const configured = origin(req);
+    if (!configured) { responder.sendBffError(res, "UPSTREAM_UNAVAILABLE", options.messages.unavailable); return false; }
+    const supplied = req.headers.origin;
+    const contentType = req.headers["content-type"];
+    if (supplied !== configured || typeof contentType !== "string" || !/^application\/json(?:;|$)/i.test(contentType)) {
+      responder.sendBffError(res, "FORBIDDEN", options.messages.forbidden); return false;
+    }
+    return true;
+  }
+  return {
+    async requestChallenge(req: HttpRequest, res: HttpResponse): Promise<void> {
+      if (!admitted(req, res)) return;
+      const parsed = operatorChallengeRequestSchema.safeParse(req.body);
+      if (!parsed.success) { responder.sendBffError(res, "BAD_REQUEST", options.messages.invalidRequest); return; }
+      const started = Date.now();
+      try {
+        await options.sessions.requestChallenge(parsed.data.email, async () => {
+          await options.padResponseTime(started, 400);
+          responder.sendBffSuccess(res, { accepted: true });
+        });
+      } catch { responder.sendBffError(res, "UPSTREAM_UNAVAILABLE", options.messages.unavailable); }
+    },
+    async verifyChallenge(req: HttpRequest, res: HttpResponse): Promise<void> {
+      if (!admitted(req, res)) return;
+      // A token-shaped refusal is authentication failure; an invalid envelope is a bad request.
+      if (!req.body || typeof req.body !== "object" || Object.keys(req.body).length !== 1 || typeof (req.body as { token?: unknown }).token !== "string") {
+        responder.sendBffError(res, "BAD_REQUEST", options.messages.invalidRequest); return;
+      }
+      const parsed = operatorChallengeVerificationSchema.safeParse(req.body);
+      if (!parsed.success) { responder.sendBffError(res, "UNAUTHORIZED", options.messages.unauthorized); return; }
+      try {
+        const session = await options.sessions.verifyChallenge(parsed.data.token);
+        if (!session) { responder.sendBffError(res, "UNAUTHORIZED", options.messages.unauthorized); return; }
+        responder.sendBffSuccess(res, operatorSessionSchema.parse(session));
+      } catch { responder.sendBffError(res, "UPSTREAM_UNAVAILABLE", options.messages.unavailable); }
+    },
+  };
+}

package/src/identity/operatorIdentityVerifier.ts

@@ -0,0 +1,19 @@
+import { createCustomerIdentityVerifier } from "./customerIdentityVerifier.js";
+import type { IdentityJwtLibraryLoader } from "./jwtLibrary.js";
+import type { IdentityVerifierPort } from "./ports.js";
+export function createOperatorIdentityVerifier(config: { issuer: string; audience: string; customerAudience: string; jwks: string }, loadJwt: IdentityJwtLibraryLoader): IdentityVerifierPort {
+  if (!config.customerAudience.trim() || config.audience === config.customerAudience) throw new Error("operator_audience_must_be_distinct");
+  // Inspect the payload returned by the same cryptographic verification, never an unverified decode.
+  return createCustomerIdentityVerifier(config, async () => {
+    const library = await loadJwt();
+    return { ...library, async jwtVerify(token, key, options) {
+      const verified = await library.jwtVerify(token, key, options);
+      const payload = verified.payload as Record<string, unknown>;
+      const { iat, exp } = payload;
+      if (payload.aud !== config.audience || typeof iat !== "number" || typeof exp !== "number"
+        || !Number.isInteger(iat) || !Number.isInteger(exp) || exp <= iat || exp - iat > 900
+        || iat > Math.floor(Date.now() / 1000) || exp <= Math.floor(Date.now() / 1000)) throw new Error("operator_token_profile_invalid");
+      return verified;
+    } };
+  });
+}

package/src/identity/operatorInvitationLifecycle.ts

@@ -0,0 +1,14 @@
+export function assertOperatorInvitationTtl(value: number): void {
+  if (!Number.isInteger(value) || value < 60 || value > 2592000) throw new Error("operator_invitation_ttl_invalid");
+}
+export function invitationFailure(identityCode: string, bffCode = "CONFLICT"): Error & { identityCode: string; bffCode: string } {
+  return Object.assign(new Error(identityCode), { identityCode, bffCode });
+}
+
+/** Pure parser; direct hosts call it before effects and pass the number to identity. */
+export function parseOperatorInvitationTtl(raw?: string): number {
+  if (raw !== undefined && !/^\d+$/.test(raw)) throw new Error("operator_invitation_ttl_invalid");
+  const value = raw === undefined ? 604800 : Number(raw);
+  assertOperatorInvitationTtl(value);
+  return value;
+}

package/src/identity/operatorInvitationPorts.ts

@@ -0,0 +1,11 @@
+import type { OperatorInvitationAcceptance, OperatorInvitationConflict, OperatorInvitationResult, OperatorMembershipSnapshot, OperatorRole } from "./contracts/operatorInvitations.js";
+export interface OperatorIdentityDirectoryPort {
+  ensurePrincipal(input: { email: string; redirectTo: string }): Promise<{ principalId: string; created: boolean }>;
+}
+export interface OperatorInvitationStore {
+  issue(input: { actorPrincipalId: string; targetPrincipalId: string; email: string; role: OperatorRole; ttlSeconds: number }): Promise<OperatorInvitationResult | { code: OperatorInvitationConflict }>;
+  read(principalId: string): Promise<OperatorMembershipSnapshot | null>;
+  /** Trusted server input only: principal must come from successful authentication. */
+  acceptOperatorInvitation(principalId: string): Promise<OperatorInvitationAcceptance>;
+  remove(input: { actorPrincipalId: string; targetPrincipalId: string; reason?: string }): Promise<{ revoked: true }>;
+}

package/src/identity/operatorPorts.ts

@@ -0,0 +1,11 @@
+export interface OperatorIdentity { principalId: string; email: string }
+export interface OperatorMembership extends OperatorIdentity { membershipState: string; role: unknown }
+export interface OperatorIdentityStore {
+  issue(input: { email: string; tokenHash: string }): Promise<{ deliverable: false } | { deliverable: true; email: string; expiresAt: string }>;
+  /** Activation and consumption commit together before signing. */
+  redeem(input: { tokenHash: string }): Promise<OperatorIdentity | null>;
+  findMembership(principalId: string): Promise<OperatorMembership | null>;
+  bootstrapFirstAdministrator(input: { email: string }): Promise<{ principalId: string; membershipState: "invited" }>;
+  pruneChallenges(input: { limit: number }): Promise<{ deleted: number }>;
+  close(): Promise<void>;
+}

package/src/identity/operatorSession.ts

@@ -0,0 +1,30 @@
+import { createHash, randomBytes } from "node:crypto";
+import type { CustomerChallengeDeliveryPort, CustomerSessionIssuerPort } from "./ports.js";
+import type { OperatorIdentityStore } from "./operatorPorts.js";
+import type { OperatorSession } from "./contracts/operatorAuth.js";
+export function createOperatorSessionService(options: {
+  store: OperatorIdentityStore; delivery: CustomerChallengeDeliveryPort; issuer: CustomerSessionIssuerPort;
+  generateToken?: () => string;
+  deliveryFailed?: (code: "operator_challenge_delivery_failed") => void;
+}) {
+  const hash = (value: string) => createHash("sha256").update(value, "utf8").digest("hex");
+  return {
+    async requestChallenge(email: string, accept?: () => Promise<void>): Promise<void> {
+      const token = options.generateToken?.() ?? randomBytes(32).toString("base64url");
+      if (!/^[A-Za-z0-9_-]{43}$/.test(token)) throw new Error("operator_challenge_generator_invalid");
+      const result = await options.store.issue({ email: email.trim().toLowerCase(), tokenHash: hash(token) });
+      // Send the generic acceptance before mailbox transport, for every eligibility result.
+      await accept?.();
+      if (!result.deliverable) return;
+      try { await options.delivery.deliver({ email: result.email, expiresAt: result.expiresAt, token }); }
+      catch { options.deliveryFailed?.("operator_challenge_delivery_failed"); }
+    },
+    async verifyChallenge(token: string): Promise<OperatorSession | null> {
+      if (!/^[A-Za-z0-9_-]{43}$/.test(token)) return null;
+      const identity = await options.store.redeem({ tokenHash: hash(token) });
+      if (!identity) return null;
+      const session = await options.issuer.issue(identity);
+      return { ...session, user: { id: identity.principalId, email: identity.email } };
+    },
+  };
+}

package/src/identity/operatorTokenAdminAuth.ts

@@ -0,0 +1,79 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+import type {
+  AdminAuthorizationResult,
+  AdminAuthPort,
+  AdminPrincipalRole,
+} from "./ports.js";
+
+const MIN_TOKEN_BYTES = 32;
+const MAX_TOKEN_BYTES = 512;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export type PlatformOperatorAuthConfig = {
+  readonly operatorToken: string;
+  readonly operatorId: string;
+};
+
+export type PlatformOperatorAllowlistCheck = (principalId: string) => Promise<boolean>;
+
+export type PlatformOperatorAuthConfigResolution =
+  | { readonly config: PlatformOperatorAuthConfig; readonly error?: undefined }
+  | { readonly config?: undefined; readonly error: "platform_operator_token_required" | "platform_operator_token_invalid" | "platform_operator_id_required" | "platform_operator_id_invalid" };
+
+function byteLength(value: string): number {
+  return Buffer.byteLength(value, "utf8");
+}
+
+
+export function resolvePlatformOperatorAuthConfig(
+  env: Record<string, string | undefined>,
+): PlatformOperatorAuthConfigResolution {
+  const operatorToken = env.PLATFORM_OPERATOR_TOKEN?.trim() ?? "";
+  if (!operatorToken) return { error: "platform_operator_token_required" };
+  const tokenBytes = byteLength(operatorToken);
+  if (tokenBytes < MIN_TOKEN_BYTES || tokenBytes > MAX_TOKEN_BYTES) {
+    return { error: "platform_operator_token_invalid" };
+  }
+
+  const operatorId = env.PLATFORM_OPERATOR_ID?.trim() ?? "";
+  if (!operatorId) return { error: "platform_operator_id_required" };
+  if (!UUID_PATTERN.test(operatorId)) return { error: "platform_operator_id_invalid" };
+  return { config: { operatorToken, operatorId: operatorId.toLowerCase() } };
+}
+
+function matchesOperatorToken(candidate: string | null, expected: string): boolean {
+  if (!candidate || byteLength(candidate) > MAX_TOKEN_BYTES) return false;
+  const actualDigest = createHash("sha256").update(candidate, "utf8").digest();
+  const expectedDigest = createHash("sha256").update(expected, "utf8").digest();
+  return timingSafeEqual(actualDigest, expectedDigest);
+}
+
+
+export function createOperatorTokenAdminAuth(
+  config: PlatformOperatorAuthConfig,
+  isOperatorAllowed: PlatformOperatorAllowlistCheck,
+): AdminAuthPort {
+  return {
+    async authorize(
+      accessToken: string | null,
+      options: { allowedRoles?: readonly AdminPrincipalRole[] } = {},
+    ): Promise<AdminAuthorizationResult> {
+      if (!matchesOperatorToken(accessToken, config.operatorToken)) {
+        return { ok: false, code: "UNAUTHORIZED", message: "Admin session required" };
+      }
+      if (options.allowedRoles && !options.allowedRoles.includes("admin")) {
+        return { ok: false, code: "FORBIDDEN", message: "Admin role required" };
+      }
+      if (!(await isOperatorAllowed(config.operatorId))) {
+        return { ok: false, code: "FORBIDDEN", message: "Admin role required" };
+      }
+      return {
+        ok: true,
+        principalId: config.operatorId,
+        role: "admin",
+        isMachineActor: true,
+      };
+    },
+  };
+}

package/src/identity/personalDataRegistry.ts

@@ -0,0 +1,8 @@
+import { PrivacyRefusal, type PersonalDataContributor, type PersonalDataContributorRegistry } from "./privacyPorts.js";
+export function createPersonalDataContributorRegistry<Context>(contributors: readonly PersonalDataContributor<Context>[], options: { requiredContributorIds: readonly string[] }): PersonalDataContributorRegistry<Context> {
+  const ids = contributors.map(c => c.id);
+  if (new Set(ids).size !== ids.length) throw new PrivacyRefusal("PRIVACY_CONTRIBUTOR_DUPLICATE");
+  if (contributors.some(c => !/^[a-z][a-z0-9.-]{0,99}$/.test(c.id) || !/^[a-z][a-z0-9.-]*\.v[1-9][0-9]*$/.test(c.version))) throw new PrivacyRefusal("PRIVACY_OWNERSHIP_UNDECLARED");
+  if (contributors.some(c => !Array.isArray(c.ownedResources) || c.ownedResources.length === 0 || c.ownedResources.some(resource => !resource.trim()))) throw new PrivacyRefusal("PRIVACY_OWNERSHIP_UNDECLARED");
+  return Object.freeze({ contributors: Object.freeze([...contributors]), missingContributors: Object.freeze(options.requiredContributorIds.filter(id => !ids.includes(id))) });
+}

package/src/identity/platformAdminAuth.ts

@@ -0,0 +1,7 @@
+export type PlatformAdminAuthorizationResult =
+  | { ok: true }
+  | { ok: false; code: "UNAUTHORIZED" | "FORBIDDEN"; message: string };
+
+export type PlatformUserAuthenticationResult =
+  | { ok: true; userId: string }
+  | { ok: false; code: "UNAUTHORIZED"; message: string };