@nacre.work/core 0.0.0

package/dist/metrics.js

@@ -0,0 +1,179 @@
+/**
+ * A minimal Prometheus registry.
+ *
+ * Dependency-free because the exposition format is four lines of rules and this
+ * container reads documents for a living — every dependency in it is something
+ * to keep patched. If the needs here outgrow histograms and gauges, replace it
+ * with prom-client rather than growing this file.
+ */
+const NAME = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+function escapeLabel(value) {
+    return value.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/"/g, '\\"');
+}
+function series(name, labels) {
+    const pairs = Object.entries(labels)
+        .filter(([, v]) => v !== '')
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${k}="${escapeLabel(v)}"`);
+    return pairs.length === 0 ? name : `${name}{${pairs.join(',')}}`;
+}
+export class Counter {
+    name;
+    help;
+    type = 'counter';
+    #values = new Map();
+    constructor(name, help) {
+        this.name = name;
+        this.help = help;
+        if (!NAME.test(name))
+            throw new Error(`not a valid metric name: ${name}`);
+    }
+    inc(labels = {}, by = 1) {
+        const key = series(this.name, labels);
+        const entry = this.#values.get(key) ?? { labels, value: 0 };
+        entry.value += by;
+        this.#values.set(key, entry);
+    }
+    render() {
+        // A counter with no observations is still reported, at zero. An absent
+        // series and a zero series look the same on a graph and mean opposite
+        // things: "nothing happened" versus "the exporter is not running".
+        if (this.#values.size === 0)
+            return [`${this.name} 0`];
+        return [...this.#values].map(([key, e]) => `${key} ${e.value}`);
+    }
+}
+export class Gauge {
+    name;
+    help;
+    type = 'gauge';
+    #values = new Map();
+    constructor(name, help) {
+        this.name = name;
+        this.help = help;
+        if (!NAME.test(name))
+            throw new Error(`not a valid metric name: ${name}`);
+    }
+    set(value, labels = {}) {
+        this.#values.set(series(this.name, labels), value);
+    }
+    reset() {
+        this.#values.clear();
+    }
+    render() {
+        if (this.#values.size === 0)
+            return [`${this.name} 0`];
+        return [...this.#values].map(([key, v]) => `${key} ${v}`);
+    }
+}
+const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+export class Histogram {
+    name;
+    help;
+    buckets;
+    type = 'histogram';
+    #series = new Map();
+    constructor(name, help, buckets = DEFAULT_BUCKETS) {
+        this.name = name;
+        this.help = help;
+        this.buckets = buckets;
+        if (!NAME.test(name))
+            throw new Error(`not a valid metric name: ${name}`);
+    }
+    observe(seconds, labels = {}) {
+        const key = series(this.name, labels);
+        const entry = this.#series.get(key) ?? {
+            labels,
+            counts: new Array(this.buckets.length).fill(0),
+            sum: 0,
+            count: 0,
+        };
+        for (let i = 0; i < this.buckets.length; i++) {
+            if (seconds <= this.buckets[i])
+                entry.counts[i] = entry.counts[i] + 1;
+        }
+        entry.sum += seconds;
+        entry.count += 1;
+        this.#series.set(key, entry);
+    }
+    /** Times `fn`, recording however it ends. A failure has a duration too. */
+    async time(labels, fn) {
+        const started = performance.now();
+        try {
+            return await fn();
+        }
+        finally {
+            this.observe((performance.now() - started) / 1000, labels);
+        }
+    }
+    render() {
+        const lines = [];
+        for (const entry of this.#series.values()) {
+            // Already cumulative, and deliberately so: `observe` increments every
+            // bucket whose bound the value is under, rather than only its own. The
+            // exposition format requires cumulative counts, and summing them here
+            // instead would be the same arithmetic done once per scrape rather than
+            // once per observation.
+            for (let i = 0; i < this.buckets.length; i++) {
+                lines.push(`${series(`${this.name}_bucket`, { ...entry.labels, le: String(this.buckets[i]) })} ${entry.counts[i]}`);
+            }
+            lines.push(`${series(`${this.name}_bucket`, { ...entry.labels, le: '+Inf' })} ${entry.count}`);
+            lines.push(`${series(`${this.name}_sum`, entry.labels)} ${entry.sum}`);
+            lines.push(`${series(`${this.name}_count`, entry.labels)} ${entry.count}`);
+        }
+        return lines;
+    }
+}
+export class Registry {
+    #metrics = [];
+    #collectors = [];
+    register(metric) {
+        if (this.#metrics.some((m) => m.name === metric.name)) {
+            throw new Error(`metric already registered: ${metric.name}`);
+        }
+        this.#metrics.push(metric);
+        return metric;
+    }
+    /**
+     * A function run before every scrape, for values that are queries rather than
+     * counters — document counts, the propagation lag, pending tombstones.
+     */
+    collect(fn) {
+        this.#collectors.push(fn);
+    }
+    async render() {
+        // A collector that fails must not blank the whole exposition: the metrics
+        // that still work are how you find out which one broke.
+        await Promise.allSettled(this.#collectors.map((fn) => fn()));
+        const lines = [];
+        for (const metric of this.#metrics) {
+            lines.push(`# HELP ${metric.name} ${metric.help}`);
+            lines.push(`# TYPE ${metric.name} ${metric.type}`);
+            lines.push(...metric.render());
+        }
+        return `${lines.join('\n')}\n`;
+    }
+}
+/**
+ * The metrics docs/config.md requires.
+ *
+ * `nacre_acl_propagation_lag_seconds` is the one with an alert on it, and the
+ * reason is worth restating where the metric is defined: it is the only
+ * external evidence that invariant I4 — a revoked grant reflected within the
+ * SLA — still holds. Everything else here describes how the system is doing.
+ * This one describes whether it is still correct.
+ */
+export function createMetrics(registry) {
+    return {
+        searchDuration: registry.register(new Histogram('nacre_search_duration_seconds', 'Search latency, end to end', [
+            0.01, 0.025, 0.05, 0.1, 0.2, 0.5, 1, 2, 5,
+        ])),
+        searchResults: registry.register(new Counter('nacre_search_results_total', 'Results returned, by layer')),
+        aclDenials: registry.register(new Counter('nacre_acl_denials_total', 'Access denials, by reason')),
+        aclPropagationLag: registry.register(new Gauge('nacre_acl_propagation_lag_seconds', 'Age in seconds of the oldest document, per organization, whose ACL tags predate the current groups_version. Alert on max() over this. The only external evidence that invariant I4 holds')),
+        ingestDuration: registry.register(new Histogram('nacre_ingest_duration_seconds', 'Indexing latency, by stage')),
+        documents: registry.register(new Gauge('nacre_documents_total', 'Documents, by organization and status')),
+        tombstonesPending: registry.register(new Gauge('nacre_tombstones_pending_total', 'Deleted documents whose vectors are not yet purged. Climbing means garbage collection is losing')),
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

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

package/dist/migrate-main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=migrate-main.d.ts.map

package/dist/migrate-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-main.d.ts","sourceRoot":"","sources":["../migrate-main.ts"],"names":[],"mappings":""}

package/dist/migrate-main.js

@@ -0,0 +1,34 @@
+import { migrate } from './db/migrate.js';
+/**
+ * The migration entry point, for the container.
+ *
+ * `pnpm migrate` runs `scripts/migrate.ts` through tsx, which is a development
+ * dependency and is not in the runtime image — so a deployment had no way to
+ * apply the schema at all. Compose started the API against an empty database,
+ * every request failed on a missing table, and the first thing a self-hoster
+ * saw was `relation "organizations" does not exist`.
+ *
+ * A separate process rather than a step inside the API: several API replicas
+ * starting at once would each try to migrate, and the one that loses the race
+ * reports a failure that is not one. Compose runs this to completion first.
+ */
+async function main() {
+    const url = process.env.NACRE_PG_URL;
+    if (url === undefined || url.length === 0) {
+        // Exit 2, like every other entry point refusing an incomplete environment.
+        console.error('NACRE_PG_URL is not set. Configuration is validated at startup and this is startup.');
+        process.exit(2);
+    }
+    const { applied, skipped } = await migrate(url);
+    console.log(JSON.stringify({
+        msg: 'migrations complete',
+        applied: applied.length,
+        skipped: skipped.length,
+        names: applied,
+    }));
+}
+main().catch((error) => {
+    console.error(JSON.stringify({ msg: 'migration failed', error: String(error) }));
+    process.exit(1);
+});
+//# sourceMappingURL=migrate-main.js.map

package/dist/migrate-main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-main.js","sourceRoot":"","sources":["../migrate-main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAEzC;;;;;;;;;;;;GAYG;AAEH,KAAK,UAAU,IAAI;IACjB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAA;IACpC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,2EAA2E;QAC3E,OAAO,CAAC,KAAK,CAAC,qFAAqF,CAAC,CAAA;QACpG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAA;IAE/C,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CAAC;QACb,GAAG,EAAE,qBAAqB;QAC1B,OAAO,EAAE,OAAO,CAAC,MAAM;QACvB,OAAO,EAAE,OAAO,CAAC,MAAM;QACvB,KAAK,EAAE,OAAO;KACf,CAAC,CACH,CAAA;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IAChF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/migrations/0001_init.sql

@@ -0,0 +1,226 @@
+-- 0001 — initial schema.
+--
+-- The source of truth for tenants, permissions, metadata, and audit. Vectors
+-- live in Qdrant and originals in S3; this holds only what needs transactions.
+--
+-- Specification: docs/authz.md and docs/architecture.md.
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+CREATE EXTENSION IF NOT EXISTS citext;
+
+-- ─────────────────────────── tenants ───────────────────────────
+
+CREATE TABLE organizations (
+    id                  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    slug                citext UNIQUE NOT NULL,
+    name                text NOT NULL,
+    vector_collection   text NOT NULL,          -- one Qdrant collection per organization
+    quotas              jsonb NOT NULL DEFAULT '{}'::jsonb,
+    groups_version      bigint NOT NULL DEFAULT 1,  -- permission cache invalidation
+    created_at          timestamptz NOT NULL DEFAULT now(),
+    deleted_at          timestamptz
+);
+
+CREATE TABLE sso_configs (
+    org_id       uuid PRIMARY KEY REFERENCES organizations(id) ON DELETE CASCADE,
+    protocol     text NOT NULL CHECK (protocol IN ('oidc','saml')),
+    issuer       text NOT NULL,
+    metadata     jsonb NOT NULL,
+    scim_enabled boolean NOT NULL DEFAULT false,
+    scim_token_hash text,
+    updated_at   timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE users (
+    id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    org_id       uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    external_id  text,                          -- sub from the IdP
+    email        citext NOT NULL,
+    role         text NOT NULL DEFAULT 'member'
+                 CHECK (role IN ('platform_admin','org_admin','workspace_admin','member')),
+    password_hash text,                         -- NULL when SSO-only
+    disabled_at  timestamptz,
+    created_at   timestamptz NOT NULL DEFAULT now(),
+    UNIQUE (org_id, email),
+    UNIQUE (org_id, external_id)
+);
+
+CREATE TABLE groups (
+    id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    org_id      uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    external_id text,
+    name        text NOT NULL,
+    UNIQUE (org_id, name)
+);
+
+-- Nested groups. Cycles are the resolver's problem to terminate on, not the
+-- schema's to prevent: see docs/authz.md, T14.
+CREATE TABLE group_members (
+    group_id     uuid NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
+    member_user  uuid REFERENCES users(id) ON DELETE CASCADE,
+    member_group uuid REFERENCES groups(id) ON DELETE CASCADE,
+    CHECK (num_nonnulls(member_user, member_group) = 1),
+    UNIQUE (group_id, member_user, member_group)
+);
+
+CREATE TABLE service_accounts (
+    id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    org_id        uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    name          text NOT NULL,
+    key_hash      text NOT NULL,
+    key_prefix    text NOT NULL,                -- first 8 characters, for display only
+    last_used_at  timestamptz,
+    revoked_at    timestamptz,
+    created_at    timestamptz NOT NULL DEFAULT now(),
+    UNIQUE (org_id, name)
+);
+CREATE INDEX ON service_accounts (key_prefix) WHERE revoked_at IS NULL;
+
+-- ─────────────────────── data structure ───────────────────────
+
+CREATE TABLE embedding_providers (
+    id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    org_id      uuid REFERENCES organizations(id) ON DELETE CASCADE,  -- NULL = global default
+    name        text NOT NULL,
+    endpoint    text NOT NULL,                  -- OpenAI-compatible URL
+    model       text NOT NULL,
+    dimensions  int  NOT NULL,
+    credentials_ref text,                       -- a reference into the secret store, never the secret
+    created_at  timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE workspaces (
+    id         uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    org_id     uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    slug       citext NOT NULL,
+    name       text NOT NULL,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    deleted_at timestamptz,
+    UNIQUE (org_id, slug)
+);
+
+CREATE TABLE layers (
+    id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    org_id        uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    workspace_id  uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+    slug          citext NOT NULL,
+    name          text NOT NULL,
+    -- This text is what the MCP search tool's generated description is built
+    -- from, so it is user-facing copy, not an internal note.
+    description   text NOT NULL DEFAULT '',
+    provider_id   uuid NOT NULL REFERENCES embedding_providers(id),
+    vector_name   text NOT NULL,                -- named vector inside the collection
+    chunk_config  jsonb NOT NULL DEFAULT '{"size":800,"overlap":120,"strategy":"recursive"}'::jsonb,
+    reindex_state jsonb,                        -- {"status":"running","shadow_vector":"v2",...}
+    created_at    timestamptz NOT NULL DEFAULT now(),
+    deleted_at    timestamptz,
+    UNIQUE (workspace_id, slug)
+);
+
+CREATE TABLE documents (
+    id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    org_id        uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    layer_id      uuid NOT NULL REFERENCES layers(id) ON DELETE CASCADE,
+    external_id   text,                         -- client-side idempotency key
+    source_type   text NOT NULL CHECK (source_type IN ('s3','url','external_id','inline')),
+    source_ref    text,
+    title         text,
+    content_hash  text NOT NULL,
+    version       int  NOT NULL DEFAULT 1,
+    status        text NOT NULL DEFAULT 'pending'
+                  CHECK (status IN ('pending','parsing','indexing','indexed','failed')),
+    error         text,
+    metadata      jsonb NOT NULL DEFAULT '{}'::jsonb,
+    chunk_count   int NOT NULL DEFAULT 0,
+    deleted_at    timestamptz,                  -- tombstone; GC clears the vectors
+    vectors_purged_at timestamptz,
+    created_at    timestamptz NOT NULL DEFAULT now(),
+    updated_at    timestamptz NOT NULL DEFAULT now(),
+    UNIQUE (layer_id, external_id)
+);
+CREATE INDEX ON documents (layer_id) WHERE deleted_at IS NULL;
+CREATE INDEX ON documents (org_id, status);
+CREATE INDEX ON documents (content_hash);
+-- The garbage-collection queue.
+CREATE INDEX ON documents (deleted_at) WHERE deleted_at IS NOT NULL AND vectors_purged_at IS NULL;
+
+-- Chunks are kept for returning text and for tracing. The vector itself is in
+-- Qdrant; this table never holds one.
+CREATE TABLE chunks (
+    id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    org_id        uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    document_id   uuid NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    ordinal       int  NOT NULL,
+    text          text NOT NULL,
+    token_count   int,
+    point_id      uuid NOT NULL,                -- point id in Qdrant
+    UNIQUE (document_id, ordinal)
+);
+
+-- ─────────────────────────── permissions ───────────────────────────
+
+CREATE TABLE grants (
+    id             uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    org_id         uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    principal_type text NOT NULL CHECK (principal_type IN ('user','group','service_account')),
+    principal_id   uuid NOT NULL,
+    scope_type     text NOT NULL CHECK (scope_type IN ('workspace','layer','document')),
+    scope_id       uuid NOT NULL,
+    permission     text NOT NULL CHECK (permission IN ('read','write','admin')),
+    effect         text NOT NULL DEFAULT 'allow' CHECK (effect IN ('allow','deny')),
+    source         text NOT NULL DEFAULT 'manual' CHECK (source IN ('manual','scim','api')),
+    created_by     uuid REFERENCES users(id),
+    created_at     timestamptz NOT NULL DEFAULT now(),
+    UNIQUE (org_id, principal_type, principal_id, scope_type, scope_id, permission)
+);
+CREATE INDEX ON grants (org_id, principal_type, principal_id);
+CREATE INDEX ON grants (org_id, scope_type, scope_id);
+
+-- ─────────────────────────── audit ───────────────────────────
+-- Event schema: docs/audit.md. Append-only — UPDATE and DELETE must be revoked
+-- from the application role, not merely avoided by it.
+
+CREATE TABLE audit_events (
+    id          bigserial PRIMARY KEY,
+    org_id      uuid NOT NULL,
+    occurred_at timestamptz NOT NULL DEFAULT now(),
+    actor_type  text NOT NULL,
+    actor_id    uuid,
+    actor_label text NOT NULL,
+    action      text NOT NULL,
+    surface     text NOT NULL CHECK (surface IN ('api','mcp','admin','system')),
+    client      text,                           -- MCP client name from _meta
+    target      jsonb NOT NULL,
+    result      text NOT NULL CHECK (result IN ('allow','deny','error')),
+    detail      jsonb NOT NULL DEFAULT '{}'::jsonb,
+    request_id  text
+);
+CREATE INDEX ON audit_events (org_id, occurred_at DESC);
+CREATE INDEX ON audit_events (org_id, actor_id, occurred_at DESC);
+CREATE INDEX ON audit_events USING gin (target);
+
+-- ─────────── second line of defense: RLS ───────────
+--
+-- The application already filters by org_id. RLS exists so that one forgotten
+-- check is a query returning nothing rather than a cross-tenant leak. The
+-- application role sets app.current_org on the connection.
+--
+-- This is defense in depth, not the mechanism. Invariant I1 is enforced in the
+-- application and verified again at serialization; do not treat RLS as a
+-- reason to skip either.
+
+ALTER TABLE documents  ENABLE ROW LEVEL SECURITY;
+ALTER TABLE chunks     ENABLE ROW LEVEL SECURITY;
+ALTER TABLE grants     ENABLE ROW LEVEL SECURITY;
+ALTER TABLE layers     ENABLE ROW LEVEL SECURITY;
+ALTER TABLE workspaces ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY org_isolation ON documents  USING (org_id = current_setting('app.current_org')::uuid);
+CREATE POLICY org_isolation ON chunks     USING (org_id = current_setting('app.current_org')::uuid);
+CREATE POLICY org_isolation ON grants     USING (org_id = current_setting('app.current_org')::uuid);
+CREATE POLICY org_isolation ON layers     USING (org_id = current_setting('app.current_org')::uuid);
+CREATE POLICY org_isolation ON workspaces USING (org_id = current_setting('app.current_org')::uuid);
+
+-- Background worker jobs run under a separate role with BYPASSRLS and are
+-- required to name org_id explicitly in every query. That role is the one place
+-- the second line of defense is off, so it gets the most review.

package/dist/migrations/0002_rls_coverage.sql

@@ -0,0 +1,128 @@
+-- 0002 — extend row-level security to the rest of the tenant tables.
+--
+-- 0001 enabled RLS on documents, chunks, grants, layers, and workspaces, and
+-- stopped there. Six more tables carry org_id and had no policy: users, groups,
+-- service_accounts, sso_configs, embedding_providers, and audit_events. The
+-- application filters all of them, which is exactly the assumption RLS exists
+-- to survive — one forgotten WHERE on `users` leaks a member list, and one on
+-- `audit_events` leaks which documents another organization's staff opened.
+--
+-- group_members carried no org_id at all, so it could not be constrained even
+-- in principle. It is the edge in the graph that effective_principals walks: a
+-- row joining a group in one organization to a user in another would hand that
+-- user every grant the group holds. Nothing writes such a row today, and
+-- nothing structural stopped one.
+
+-- ─────────────────── group_members needs a tenant column ───────────────────
+
+ALTER TABLE group_members ADD COLUMN org_id uuid REFERENCES organizations(id) ON DELETE CASCADE;
+
+UPDATE group_members gm SET org_id = g.org_id FROM groups g WHERE g.id = gm.group_id;
+
+ALTER TABLE group_members ALTER COLUMN org_id SET NOT NULL;
+
+-- Both endpoints must live in the org the row claims. A composite foreign key
+-- is what makes that checkable by the database rather than by whoever writes
+-- the insert.
+ALTER TABLE groups            ADD CONSTRAINT groups_id_org_key            UNIQUE (id, org_id);
+ALTER TABLE users             ADD CONSTRAINT users_id_org_key             UNIQUE (id, org_id);
+
+ALTER TABLE group_members
+    ADD CONSTRAINT group_members_group_in_org
+    FOREIGN KEY (group_id, org_id) REFERENCES groups (id, org_id) ON DELETE CASCADE;
+
+ALTER TABLE group_members
+    ADD CONSTRAINT group_members_user_in_org
+    FOREIGN KEY (member_user, org_id) REFERENCES users (id, org_id) ON DELETE CASCADE;
+
+ALTER TABLE group_members
+    ADD CONSTRAINT group_members_nested_group_in_org
+    FOREIGN KEY (member_group, org_id) REFERENCES groups (id, org_id) ON DELETE CASCADE;
+
+CREATE INDEX ON group_members (org_id, group_id);
+
+-- ─────────────────────────── the remaining policies ───────────────────────────
+
+ALTER TABLE users               ENABLE ROW LEVEL SECURITY;
+ALTER TABLE groups              ENABLE ROW LEVEL SECURITY;
+ALTER TABLE group_members       ENABLE ROW LEVEL SECURITY;
+ALTER TABLE service_accounts    ENABLE ROW LEVEL SECURITY;
+ALTER TABLE sso_configs         ENABLE ROW LEVEL SECURITY;
+ALTER TABLE audit_events        ENABLE ROW LEVEL SECURITY;
+ALTER TABLE embedding_providers ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY org_isolation ON users            USING (org_id = current_setting('app.current_org')::uuid);
+CREATE POLICY org_isolation ON groups           USING (org_id = current_setting('app.current_org')::uuid);
+CREATE POLICY org_isolation ON group_members    USING (org_id = current_setting('app.current_org')::uuid);
+CREATE POLICY org_isolation ON service_accounts USING (org_id = current_setting('app.current_org')::uuid);
+CREATE POLICY org_isolation ON sso_configs      USING (org_id = current_setting('app.current_org')::uuid);
+CREATE POLICY org_isolation ON audit_events     USING (org_id = current_setting('app.current_org')::uuid);
+
+-- embedding_providers is the one exception, and it is a real one: a row with a
+-- NULL org_id is the installation-wide default model, readable by every
+-- organization by design. The policy allows exactly that and nothing else — a
+-- provider belonging to another tenant stays invisible, including the endpoint
+-- and the credentials reference.
+CREATE POLICY org_isolation ON embedding_providers
+    USING (org_id IS NULL OR org_id = current_setting('app.current_org')::uuid);
+
+-- Writing a global default is not something a tenant may do.
+CREATE POLICY org_writes_own ON embedding_providers
+    FOR INSERT WITH CHECK (org_id = current_setting('app.current_org')::uuid);
+
+-- ─────────────────────── RLS that actually applies ───────────────────────
+--
+-- ENABLE ROW LEVEL SECURITY alone protects nothing from the role that owns the
+-- tables, and nothing at all from a superuser. Migrations run as the owner, so
+-- in any deployment where the application reuses that connection — which is
+-- the default until somebody deliberately splits the roles — every policy in
+-- 0001 was inert. It was verified inert: a connection scoped to org B could
+-- read org A's documents, layers, and users.
+--
+-- FORCE makes the policies apply to the owner too. Superusers still bypass
+-- them, which is why the application must not connect as one.
+
+ALTER TABLE documents           FORCE ROW LEVEL SECURITY;
+ALTER TABLE chunks              FORCE ROW LEVEL SECURITY;
+ALTER TABLE grants              FORCE ROW LEVEL SECURITY;
+ALTER TABLE layers              FORCE ROW LEVEL SECURITY;
+ALTER TABLE workspaces          FORCE ROW LEVEL SECURITY;
+ALTER TABLE users               FORCE ROW LEVEL SECURITY;
+ALTER TABLE groups              FORCE ROW LEVEL SECURITY;
+ALTER TABLE group_members       FORCE ROW LEVEL SECURITY;
+ALTER TABLE service_accounts    FORCE ROW LEVEL SECURITY;
+ALTER TABLE sso_configs         FORCE ROW LEVEL SECURITY;
+ALTER TABLE audit_events        FORCE ROW LEVEL SECURITY;
+ALTER TABLE embedding_providers FORCE ROW LEVEL SECURITY;
+
+-- ─────────────────────────── the audit log is append-only ───────────────────────────
+--
+-- docs/audit.md requires this at the database level rather than by convention.
+-- The application role gets INSERT and SELECT; UPDATE and DELETE are not
+-- granted, so a bug cannot rewrite history and neither can an attacker holding
+-- the application's credentials.
+--
+-- The role is created here if it does not exist so that a fresh development
+-- database behaves like production. Deployments that manage roles externally
+-- can drop this block; the REVOKE below is the part that matters.
+
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'nacre_app') THEN
+        CREATE ROLE nacre_app NOLOGIN;
+    END IF;
+END
+$$;
+
+GRANT SELECT, INSERT ON audit_events TO nacre_app;
+REVOKE UPDATE, DELETE ON audit_events FROM nacre_app;
+GRANT USAGE, SELECT ON SEQUENCE audit_events_id_seq TO nacre_app;
+
+-- Everything else the application touches. audit_events is deliberately not in
+-- this list; it was granted narrowly above and must stay that way.
+GRANT USAGE ON SCHEMA public TO nacre_app;
+GRANT SELECT, INSERT, UPDATE, DELETE ON
+    organizations, users, groups, group_members, service_accounts, sso_configs,
+    embedding_providers, workspaces, layers, documents, chunks, grants
+    TO nacre_app;
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO nacre_app;

package/dist/migrations/0003_groups_version.sql

@@ -0,0 +1,48 @@
+-- 0003 — make groups_version move on its own.
+--
+-- 0001 gave organizations a groups_version and described it as "permission
+-- cache invalidation", and nothing incremented it. A cache keyed on a value
+-- that never changes is a cache that never invalidates, so every effective
+-- principals entry would have gone stale on the first membership change and
+-- stayed stale until its TTL expired — which is the difference between
+-- invariant I4 holding by construction and holding if the clock cooperates.
+--
+-- Incrementing it in the database rather than in the application is the point.
+-- Group membership is written by SCIM, by the admin UI, and by the API, and a
+-- version bumped by whichever of those remembered would be a version that
+-- lies. There is one writer here: Postgres.
+
+CREATE OR REPLACE FUNCTION bump_groups_version() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+    target uuid;
+BEGIN
+    target := COALESCE(NEW.org_id, OLD.org_id);
+    UPDATE organizations SET groups_version = groups_version + 1 WHERE id = target;
+    RETURN NULL;   -- AFTER trigger; the return value is ignored
+END
+$$;
+
+-- Statement-level, not row-level: a SCIM sync replacing a hundred memberships
+-- should move the version once, not a hundred times, and every reader only
+-- cares that it moved.
+CREATE TRIGGER group_members_bump_version
+    AFTER INSERT OR UPDATE OR DELETE ON group_members
+    FOR EACH ROW EXECUTE FUNCTION bump_groups_version();
+
+-- Groups themselves matter too: deleting a group revokes everything it granted,
+-- and the cascade to group_members does not necessarily fire a statement the
+-- reader can see.
+CREATE TRIGGER groups_bump_version
+    AFTER INSERT OR UPDATE OR DELETE ON groups
+    FOR EACH ROW EXECUTE FUNCTION bump_groups_version();
+
+-- The function runs as its definer so it can update organizations, which the
+-- application role can read but must not rewrite at will.
+ALTER FUNCTION bump_groups_version() SECURITY DEFINER;
+REVOKE ALL ON FUNCTION bump_groups_version() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION bump_groups_version() TO nacre_app;
+
+-- Reading the version is on the search path, so it gets an index rather than a
+-- sequential scan of organizations on every query.
+CREATE INDEX IF NOT EXISTS organizations_groups_version_idx ON organizations (id, groups_version);