@nacre.work/core 0.1.0 → 0.3.0

package/dist/db/migrate.js

@@ -53,6 +53,62 @@ async function checksum(sql) {
     const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(sql));
     return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
 }
+/**
+ * Refuse, before applying anything, if the connected role cannot finish.
+ *
+ * Every tenant table has `FORCE ROW LEVEL SECURITY`, and `FORCE` is what makes
+ * the policy apply to the table's **owner** as well. Migrations run as the
+ * owner and several of them read a tenant table — 0006 checks for duplicate
+ * layer slugs, 0007 backfills a lease column, 0017 rewrites a role, 0018
+ * dedupes group members. Each of those evaluates
+ * `current_setting('app.current_org')`, which is unset during a migration, so
+ * the statement fails with:
+ *
+ *     ERROR: unrecognized configuration parameter "app.current_org"
+ *
+ * That message names nothing an operator can act on. It says nothing about
+ * roles, nothing about row-level security, and it arrives at migration 0006
+ * rather than at the start — five migrations of schema already applied.
+ *
+ * It has never been seen because development connects as a superuser, and a
+ * superuser bypasses row-level security entirely. It appears the moment an
+ * operator follows `docs/config.md` and stops doing that, which is the same
+ * shape as the two subsystems already found this way.
+ *
+ * So the requirement is stated once, up front, with the SQL that satisfies it.
+ * The `WITH ADMIN OPTION` line is in the message even though it is not what is
+ * being checked: migration 0008 runs `GRANT nacre_worker TO nacre_app` and
+ * plain membership is not enough to grant a role onward. That migration's own
+ * hint says to grant membership, which does not fix it — and 0008 has been
+ * applied everywhere, so its text is checksummed and cannot be corrected in
+ * place. Naming the whole block here is what stops an operator satisfying one
+ * requirement and meeting the next one on the following run.
+ *
+ * Only called when there is something to apply, so re-running `migrate` on an
+ * up-to-date database stays a no-op whatever role it connects as.
+ */
+export async function requireMigrationPrivileges(client) {
+    const { rows } = await client.query('SELECT rolsuper AS superuser, rolbypassrls AS bypassrls FROM pg_roles WHERE rolname = current_user');
+    const role = rows[0];
+    if (role === undefined || role.superuser || role.bypassrls)
+        return;
+    throw new Error('the role running migrations can neither bypass row-level security nor is a ' +
+        'superuser, and several migrations read tenant tables. Every one of those ' +
+        'tables has FORCE ROW LEVEL SECURITY, which applies the policy to the owner ' +
+        'too, and the policy reads app.current_org — unset during a migration. The ' +
+        'migration would fail partway through with "unrecognized configuration ' +
+        'parameter \\"app.current_org\\"", which names none of this.\n\n' +
+        'Run this once as a superuser:\n\n' +
+        '  ALTER ROLE <the role in NACRE_PG_URL> BYPASSRLS;\n' +
+        '  CREATE ROLE nacre_worker NOLOGIN BYPASSRLS;  -- if it does not exist\n' +
+        '  GRANT nacre_worker TO <the role in NACRE_PG_URL> WITH ADMIN OPTION;\n\n' +
+        'WITH ADMIN OPTION is required and plain membership is not: migration 0008 ' +
+        'grants nacre_worker onward to nacre_app, and only a member holding ADMIN ' +
+        'may do that.\n\n' +
+        'This role is the one that owns the tables and runs migrations. It is not ' +
+        'the role the application connects as — that one must not bypass row-level ' +
+        'security and must not be able to create tables.');
+}
 /**
  * Apply every migration that has not been applied yet.
  *
@@ -79,6 +135,11 @@ export async function migrate(connectionString, migrations = loadMigrations()) {
         await client.query(LEDGER);
         const { rows } = await client.query('SELECT name, checksum FROM schema_migrations');
         const ledger = new Map(rows.map((r) => [r.name, r.checksum]));
+        // Only when there is work to do. A re-run against an up-to-date database
+        // applies nothing, so the privileges it would need are not needed.
+        if (migrations.some((m) => !ledger.has(m.name))) {
+            await requireMigrationPrivileges(client);
+        }
         for (const migration of migrations) {
             const sum = await checksum(migration.sql);
             const recorded = ledger.get(migration.name);

package/dist/db/migrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../db/migrate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../db/migrate.ts"],"names":[],"mappings":"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"}

package/dist/extensions.d.ts

@@ -0,0 +1,298 @@
+import type { OrgRole, Permission, Principal } from './types.js';
+import type { AccessPlan, ResolveInput } from './authz/resolve.js';
+/**
+ * The points a commercial module plugs into, and the loader that lets one do so
+ * without this repository knowing it exists.
+ *
+ * Four of them — `registerAuthProvider`, `registerAuthzResolver`,
+ * `registerAuditSink`, `mountAdminRoutes` — `nacre-enterprise` named before
+ * there was a module to write. The fifth, `registerIngestGate`, is the other
+ * direction: a point the core declares for a capability the schema always had
+ * and nothing enforced (`max_documents`), designed so the open half is complete
+ * and correct with no gate registered.
+ *
+ * `nacre-enterprise` has named these since before there was a module to write —
+ * `registerAuthProvider`, `registerAuthzResolver`, `registerAuditSink`,
+ * `mountAdminRoutes` — and nothing here declared them. That document was the
+ * only place they existed, which made "plug into points declared by
+ * `@nacre.work/core`" a sentence about a thing that was not there.
+ *
+ * ## The boundary is the reason for the shape
+ *
+ * The core's CI fails if anything under `packages/` or `services/` mentions the
+ * enterprise package by name, and that check is what keeps the open half
+ * honest: it cannot import the closed half even by accident. So a module cannot
+ * be wired in by `main.ts` importing it. It is named in configuration
+ * (`NACRE_MODULES`), imported dynamically here, and registers itself.
+ *
+ * A registry is therefore not a style preference — it is the only shape that
+ * satisfies "the core must not know this repository exists" while still letting
+ * a deployment run both halves in one process.
+ *
+ * ## What the registry refuses
+ *
+ * **Registration is only open while modules are loading.** Anything registered
+ * afterwards would be registered after the surfaces were composed, so it would
+ * be configured, look present, and never be consulted — the failure this file
+ * exists to prevent, one level up.
+ *
+ * **One resolver, and a second is an error rather than a replacement.** Two
+ * answers to "who decides access" is not something to settle by precedence: the
+ * loser stays loaded, appears to be in force, and is not. The same argument
+ * `loadJwtKeys` makes about a secret and a key reference.
+ *
+ * Sinks, providers and routes are lists, because more than one of each is a
+ * coherent thing to want and none of them decides access on its own.
+ *
+ * ## The core is complete with nothing plugged in
+ *
+ * Every default here is the behaviour this repository already had: the built-in
+ * resolver, no extra credential types, no extra sinks, no extra routes. A
+ * deployment that sets no modules gets exactly the code path it got before this
+ * file existed, and the tests that prove the permission model still run against
+ * the built-in resolver because that is what is registered.
+ */
+/**
+ * A replacement for permission evaluation.
+ *
+ * **This is the only interface in this repository that can break the six
+ * invariants from outside it.** A module that implements it takes over the
+ * question every other rule depends on, so `nacre-enterprise/CLAUDE.md` binds
+ * it to the same document the built-in one is written from: it does not relax
+ * rule 6, and it does not return `403` where the core returns `404`.
+ *
+ * The signature is deliberately the built-in one. A resolver that needed extra
+ * inputs would be a change to `ResolveInput` here, in the open half, reviewed
+ * like any other change to the model — not a private extension of it.
+ */
+export interface AuthzResolver {
+    resolve(input: ResolveInput, permission: Permission): AccessPlan;
+}
+/** What a credential resolves to. Structurally the API's `AuthContext`. */
+export interface ResolvedPrincipal {
+    /** From the credential, never from the request. Invariant 1. */
+    readonly orgId: string;
+    readonly principal: Principal;
+    readonly role: OrgRole;
+}
+/**
+ * A credential type the core does not understand.
+ *
+ * Consulted only after the built-in paths decline, and only for a bearer token
+ * that is not a JWT this deployment can verify and not a `nacre_sk_` key — so a
+ * provider cannot shadow either. `undefined` means "not mine", which is not the
+ * same as "invalid": every refusal still ends in the one `401` with the one
+ * message, because distinguishing them is what invariant 4 forbids one level
+ * down.
+ */
+export interface AuthProvider {
+    /** For the startup line and for errors. Not shown to a caller. */
+    readonly name: string;
+    authenticate(credential: string): Promise<ResolvedPrincipal | undefined>;
+}
+/**
+ * One recorded access, as handed to a sink.
+ *
+ * Declared here rather than in `packages/api` because a sink is registered from
+ * outside both, and a second structurally-identical definition is two things
+ * that have to agree with nothing making them.
+ */
+export interface AuditEvent {
+    readonly orgId: string;
+    readonly actor: string;
+    readonly action: string;
+    readonly result: 'allow' | 'deny' | 'error';
+    readonly detail: Record<string, unknown>;
+    readonly requestId: string;
+    /** Which surface the call came in on. Defaults to `api` at the writer. */
+    readonly surface?: 'api' | 'mcp' | 'admin' | 'system';
+    /** What the call was about, as `docs/audit.md` specifies it. */
+    readonly target?: Record<string, unknown>;
+}
+/**
+ * Somewhere else an event goes, **in addition to** the table.
+ *
+ * Never instead of it. The journal is append-only and is what an auditor reads;
+ * a forwarder that could replace it would make the guarantee depend on a
+ * network hop. `docs/audit.md`'s SIEM export is this.
+ */
+export interface AuditSink {
+    readonly name: string;
+    write(event: AuditEvent): Promise<void>;
+}
+/** A request as an admin route sees it — no framework, no server type. */
+export interface AdminRequest {
+    readonly method: string;
+    readonly path: string;
+    /** Capture groups from `pattern`, in order. */
+    readonly params: readonly string[];
+    readonly query: URLSearchParams;
+    readonly body: unknown;
+    /** Already authenticated. A route never sees an anonymous request. */
+    readonly auth: ResolvedPrincipal;
+}
+export interface AdminResponse {
+    readonly status: number;
+    readonly body?: unknown;
+}
+/**
+ * A route a module adds under `/v1/admin/`.
+ *
+ * Confined to that prefix by the mounter rather than by convention: a module
+ * that could mount `/v1/search` would be replacing a surface the open half
+ * documents and tests, which is a different thing from extending it.
+ */
+export interface AdminRoute {
+    readonly method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+    /** Matched against the path. Must be anchored under `/v1/admin/`. */
+    readonly pattern: RegExp;
+    handle(request: AdminRequest): Promise<AdminResponse>;
+}
+/**
+ * What an ingest gate is told about a document before it is stored.
+ *
+ * Metadata, never the bytes. The gate decides whether this document may be
+ * accepted at all — a quota, a suspension, a per-source rule — and for that it
+ * needs to know the tenant, the layer and how big the thing is, not its
+ * content. Keeping the content out is the same discipline `rejectTenantOverride`
+ * follows: a document body does not belong in something that gets passed around,
+ * logged and put into a refusal message.
+ */
+export interface IngestContext {
+    /** From the credential. Invariant 1. */
+    readonly orgId: string;
+    readonly layerId: string;
+    readonly principal: Principal;
+    readonly role: OrgRole;
+    readonly externalId: string;
+    /** The document's size in bytes, for a gate that bounds volume. */
+    readonly bytes: number;
+}
+/**
+ * A gate's answer. Admit, or refuse with a reason and the 4xx to answer with.
+ *
+ * A refusal is **not** a `404`: the caller has already been shown to hold
+ * `write` on the layer by the time a gate runs, so the layer's existence is not
+ * a secret this hides — unlike the write check itself, which returns `404` for
+ * absent and unpermitted alike. A quota or a suspension is a real answer a
+ * caller with access is entitled to, so it defaults to `403` and carries a
+ * reason.
+ */
+export type IngestVerdict = {
+    readonly admit: true;
+} | {
+    readonly admit: false;
+    readonly status?: number;
+    readonly reason: string;
+};
+/**
+ * A check run before a document is accepted, in addition to the permission
+ * check the core already does.
+ *
+ * A list, and every gate must admit — one deny refuses the ingest, with that
+ * gate's reason. Gates decide admission, not access: a gate cannot *grant* an
+ * ingest the permission model would refuse, because it runs only after
+ * `write` has been established. It can only subtract, which is why more than one
+ * is coherent and why the default — no gates — is the open core accepting every
+ * document a caller may write, exactly as it did before this point existed.
+ *
+ * `max_documents`, which the schema has carried since 0001 and nothing enforced,
+ * is the first user: a commercial `tenancy` gate that counts a tenant's live
+ * documents and refuses over the quota.
+ */
+export interface IngestGate {
+    readonly name: string;
+    admit(context: IngestContext): Promise<IngestVerdict>;
+}
+export declare function registerAuthzResolver(resolver: AuthzResolver): void;
+export declare function registerAuthProvider(provider: AuthProvider): void;
+export declare function registerAuditSink(sink: AuditSink): void;
+export declare function registerIngestGate(gate: IngestGate): void;
+export declare const ADMIN_PREFIX = "/v1/admin/";
+export declare function mountAdminRoutes(...routes: readonly AdminRoute[]): void;
+/**
+ * Import the named modules and let them register, then close registration.
+ *
+ * Dynamic by name, from configuration, which is what keeps the enterprise
+ * package's name out of this repository's source — the `boundary` job greps for
+ * it, and a static import would be the leak that job exists to catch.
+ *
+ * A module that cannot be imported is a startup failure, not a warning. The
+ * whole point of naming one is that a deployment is paying for what it does,
+ * and starting without it would silently be a different product.
+ */
+export declare function loadModules(names: readonly string[], importer?: (name: string) => Promise<unknown>): Promise<void>;
+/**
+ * The resolver in force.
+ *
+ * The built-in one unless a module replaced it, which is what makes the core
+ * complete with nothing plugged in. Read per call rather than captured, so
+ * there is no window in which a surface holds a stale one.
+ */
+export declare function activeResolver(): AuthzResolver;
+export declare const authProviders: () => readonly AuthProvider[];
+export declare const auditSinks: () => readonly AuditSink[];
+export declare const adminRoutes: () => readonly AdminRoute[];
+/** A refused ingest, as `admitIngest` reports it. */
+export interface IngestRefusal {
+    readonly module: string;
+    readonly status: number;
+    readonly reason: string;
+}
+/**
+ * Run every gate, in order, and report the first refusal.
+ *
+ * `undefined` is admission: no gates registered, or every one admitted, which
+ * is why the open core accepts what a caller may write. The first deny stops the
+ * rest — a document refused by one gate is refused, and asking the others would
+ * be work whose answer cannot change the outcome. The default status is `403`,
+ * so a gate that only sets a reason still refuses with a status a caller with
+ * access can act on rather than a `404` that would hide the layer it just wrote
+ * a check against.
+ */
+export declare function admitIngest(context: IngestContext): Promise<IngestRefusal | undefined>;
+/** Anything that records an event. Structurally the API's `audit` port. */
+export interface AuditWriter {
+    write(event: AuditEvent): Promise<void>;
+}
+/**
+ * Record the event, then hand it to every sink.
+ *
+ * A decorator over the port rather than something the Postgres adapter does,
+ * which is where it started and which put it one layer too low: forwarding is a
+ * property of *an event having been recorded*, not of which adapter recorded it.
+ * A second adapter — or a surface handed a different port — would have been a
+ * SIEM silently missing a class of events, with nothing to notice it by.
+ *
+ * The table first and never the reverse. The journal is what an auditor reads
+ * and what the append-only grant protects, so a forwarder must not be able to
+ * make a row conditional on a network hop succeeding.
+ *
+ * A sink that throws does not fail the request. It is a copy of something
+ * already durably recorded, and turning a collector outage into a 500 on every
+ * authenticated call would take the installation down to protect a duplicate.
+ *
+ * Applying it twice is a no-op, so a construction site that wraps a port
+ * already wrapped does not double every event in the deployment's SIEM.
+ */
+export declare function withAuditSinks<T extends AuditWriter>(port: T, onError?: (sink: string, event: AuditEvent, error: unknown) => void): T;
+/** What was loaded, for the startup line. An operator needs to see it. */
+export declare function loadedExtensions(): {
+    resolver: string | null;
+    providers: string[];
+    sinks: string[];
+    routes: number;
+    gates: string[];
+};
+/**
+ * Empty the registry. **Tests only**, and named so that is unmistakable.
+ *
+ * A process does not unload a module, so there is no production reason to call
+ * this — but a test file that registered one would otherwise leak it into every
+ * test after it, which is exactly the shape of failure a global registry earns
+ * if nobody gives it a way out.
+ */
+export declare function resetExtensionsForTests(): void;
+/** Open registration without importing anything. **Tests only.** */
+export declare function withLoadingModuleForTests<T>(name: string, fn: () => T): T;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../extensions.ts"],"names":[],"mappings":"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"}

package/dist/extensions.js

@@ -0,0 +1,246 @@
+import { resolve as builtInResolve } from './authz/resolve.js';
+const registry = { resolver: undefined, providers: [], sinks: [], routes: [], gates: [] };
+/** Which module is registering, or `undefined` when registration is closed. */
+let loading;
+class ExtensionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ExtensionError';
+    }
+}
+function mustBeLoading(what) {
+    if (loading === undefined) {
+        throw new ExtensionError(`${what} was registered outside module loading. Extensions are read once, ` +
+            'when the surfaces are composed, so anything registered afterwards would ' +
+            'be configured and never consulted. Register from the module body, which ' +
+            'runs during loadModules().');
+    }
+    return loading;
+}
+export function registerAuthzResolver(resolver) {
+    const module = mustBeLoading('an authorization resolver');
+    if (registry.resolver !== undefined) {
+        // Refused rather than replaced. See the note at the top: the loser would
+        // stay loaded and appear to be in force.
+        throw new ExtensionError(`two authorization resolvers were registered — ${registry.resolver.module} ` +
+            `and ${module}. There is one answer to who decides access and no order ` +
+            'of precedence worth inventing. Load one.');
+    }
+    registry.resolver = { module, value: resolver };
+}
+export function registerAuthProvider(provider) {
+    registry.providers.push({ module: mustBeLoading('an auth provider'), value: provider });
+}
+export function registerAuditSink(sink) {
+    registry.sinks.push({ module: mustBeLoading('an audit sink'), value: sink });
+}
+export function registerIngestGate(gate) {
+    registry.gates.push({ module: mustBeLoading('an ingest gate'), value: gate });
+}
+export const ADMIN_PREFIX = '/v1/admin/';
+/**
+ * Paths the pattern is asked about directly.
+ *
+ * Not a proof and not meant as one — the anchor check above is the guarantee.
+ * This catches the thing the anchor check cannot see, which is a top-level
+ * alternation: `^/v1/admin/x|^/v1/search` starts with the right prefix and
+ * matches a documented surface anyway. The list is the surfaces where being
+ * wrong costs the most, plus the two near misses on the prefix itself.
+ */
+const MUST_NOT_MATCH = [
+    '/v1/search',
+    '/v1/documents/00000000-0000-0000-0000-000000000000',
+    '/v1/grants',
+    '/v1/layers',
+    '/v1/workspaces',
+    '/v1/audit',
+    '/v1/auth/login',
+    '/v1/health',
+    '/.well-known/jwks.json',
+    '/v1/admin',
+    '/v1/adminish/things',
+];
+export function mountAdminRoutes(...routes) {
+    const module = mustBeLoading('admin routes');
+    for (const route of routes) {
+        // Checked here rather than trusted. A route outside the prefix would be a
+        // module replacing a documented surface rather than adding to one, and the
+        // dispatcher would happily serve it.
+        //
+        // Anchored, not merely containing: `/v1/admin/x` without the `^` matches
+        // `/v1/search?q=/v1/admin/x` shaped paths as readily as the intended one,
+        // and the whole value of the prefix is that it is a prefix.
+        //
+        // `\/` is unescaped first, because `/^\/v1\/admin\/x$/.source` is
+        // `^\/v1\/admin\/x$` while `new RegExp('^/v1/admin/x').source` is
+        // `^/v1/admin/x` — the same pattern, two spellings. A check on the raw
+        // source accepts one and refuses the other, which makes it a check on how
+        // the author escaped rather than on what the pattern matches. `\/` in a
+        // pattern means the character `/` and nothing else, so this rewrite is
+        // exact rather than a guess.
+        // `g` and `y` make a pattern stateful: `test` and `exec` advance
+        // `lastIndex` and the next call starts from there, so the same request
+        // path matches or does not depending on what was dispatched before it.
+        // Refused rather than worked around by resetting, because a route that
+        // only works because the dispatcher remembers to clear a field is a route
+        // that breaks the first time someone matches it somewhere else.
+        if (route.pattern.global || route.pattern.sticky) {
+            throw new ExtensionError(`${module} mounted a route whose pattern carries the ` +
+                `${route.pattern.global ? 'g' : 'y'} flag: ${String(route.pattern)}. ` +
+                'A stateful pattern matches or does not depending on what was ' +
+                'matched before it. Drop the flag.');
+        }
+        const source = route.pattern.source.replaceAll('\\/', '/');
+        if (!source.startsWith(`^${ADMIN_PREFIX}`)) {
+            throw new ExtensionError(`${module} mounted a route whose pattern is not anchored under ` +
+                `${ADMIN_PREFIX}: ${route.pattern.source}. Modules extend the admin ` +
+                'surface; they do not replace the documented ones.');
+        }
+        for (const path of MUST_NOT_MATCH) {
+            if (route.pattern.test(path)) {
+                throw new ExtensionError(`${module} mounted a route anchored under ${ADMIN_PREFIX} that also ` +
+                    `matches ${path}. A pattern can leave the prefix through a ` +
+                    'top-level alternation; this one does. Mount one route per path.');
+            }
+        }
+    }
+    // Every route checked before any is kept, so a refused batch mounts none of
+    // itself. A partial mount would be a module half in force, which is the state
+    // this file refuses everywhere else.
+    for (const route of routes)
+        registry.routes.push({ module, value: route });
+}
+/**
+ * Import the named modules and let them register, then close registration.
+ *
+ * Dynamic by name, from configuration, which is what keeps the enterprise
+ * package's name out of this repository's source — the `boundary` job greps for
+ * it, and a static import would be the leak that job exists to catch.
+ *
+ * A module that cannot be imported is a startup failure, not a warning. The
+ * whole point of naming one is that a deployment is paying for what it does,
+ * and starting without it would silently be a different product.
+ */
+export async function loadModules(names, importer = (name) => import(/* @vite-ignore */ name)) {
+    for (const name of names) {
+        loading = name;
+        try {
+            await importer(name);
+        }
+        catch (cause) {
+            throw new ExtensionError(`module ${name} could not be loaded: ${String(cause)}`);
+        }
+        finally {
+            loading = undefined;
+        }
+    }
+}
+/**
+ * The resolver in force.
+ *
+ * The built-in one unless a module replaced it, which is what makes the core
+ * complete with nothing plugged in. Read per call rather than captured, so
+ * there is no window in which a surface holds a stale one.
+ */
+export function activeResolver() {
+    return registry.resolver?.value ?? { resolve: builtInResolve };
+}
+export const authProviders = () => registry.providers.map((p) => p.value);
+export const auditSinks = () => registry.sinks.map((s) => s.value);
+export const adminRoutes = () => registry.routes.map((r) => r.value);
+/**
+ * Run every gate, in order, and report the first refusal.
+ *
+ * `undefined` is admission: no gates registered, or every one admitted, which
+ * is why the open core accepts what a caller may write. The first deny stops the
+ * rest — a document refused by one gate is refused, and asking the others would
+ * be work whose answer cannot change the outcome. The default status is `403`,
+ * so a gate that only sets a reason still refuses with a status a caller with
+ * access can act on rather than a `404` that would hide the layer it just wrote
+ * a check against.
+ */
+export async function admitIngest(context) {
+    for (const gate of registry.gates) {
+        const verdict = await gate.value.admit(context);
+        if (!verdict.admit) {
+            return { module: gate.value.name, status: verdict.status ?? 403, reason: verdict.reason };
+        }
+    }
+    return undefined;
+}
+const FANNED_OUT = Symbol.for('nacre.auditSinksApplied');
+/**
+ * Record the event, then hand it to every sink.
+ *
+ * A decorator over the port rather than something the Postgres adapter does,
+ * which is where it started and which put it one layer too low: forwarding is a
+ * property of *an event having been recorded*, not of which adapter recorded it.
+ * A second adapter — or a surface handed a different port — would have been a
+ * SIEM silently missing a class of events, with nothing to notice it by.
+ *
+ * The table first and never the reverse. The journal is what an auditor reads
+ * and what the append-only grant protects, so a forwarder must not be able to
+ * make a row conditional on a network hop succeeding.
+ *
+ * A sink that throws does not fail the request. It is a copy of something
+ * already durably recorded, and turning a collector outage into a 500 on every
+ * authenticated call would take the installation down to protect a duplicate.
+ *
+ * Applying it twice is a no-op, so a construction site that wraps a port
+ * already wrapped does not double every event in the deployment's SIEM.
+ */
+export function withAuditSinks(port, onError = () => { }) {
+    if (port[FANNED_OUT] === true)
+        return port;
+    const wrapped = {
+        write: async (event) => {
+            await port.write(event);
+            for (const sink of auditSinks()) {
+                try {
+                    await sink.write(event);
+                }
+                catch (error) {
+                    onError(sink.name, event, error);
+                }
+            }
+        },
+    };
+    return Object.assign(Object.create(port), wrapped, { [FANNED_OUT]: true });
+}
+/** What was loaded, for the startup line. An operator needs to see it. */
+export function loadedExtensions() {
+    return {
+        resolver: registry.resolver?.module ?? null,
+        providers: registry.providers.map((p) => `${p.module}:${p.value.name}`),
+        sinks: registry.sinks.map((s) => `${s.module}:${s.value.name}`),
+        routes: registry.routes.length,
+        gates: registry.gates.map((g) => `${g.module}:${g.value.name}`),
+    };
+}
+/**
+ * Empty the registry. **Tests only**, and named so that is unmistakable.
+ *
+ * A process does not unload a module, so there is no production reason to call
+ * this — but a test file that registered one would otherwise leak it into every
+ * test after it, which is exactly the shape of failure a global registry earns
+ * if nobody gives it a way out.
+ */
+export function resetExtensionsForTests() {
+    registry.resolver = undefined;
+    registry.providers.length = 0;
+    registry.sinks.length = 0;
+    registry.routes.length = 0;
+    registry.gates.length = 0;
+    loading = undefined;
+}
+/** Open registration without importing anything. **Tests only.** */
+export function withLoadingModuleForTests(name, fn) {
+    loading = name;
+    try {
+        return fn();
+    }
+    finally {
+        loading = undefined;
+    }
+}
+//# sourceMappingURL=extensions.js.map

package/dist/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../extensions.ts"],"names":[],"mappings":"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"}