@atlasauth/pca-rag 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlas Authorization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# @atlasauth/pca-rag
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fine-grained authorization for RAG, built on Proof-Carrying Authority (PCA). At retrieval time it filters candidate documents down to the ones a given principal may see, deciding each one with the PCA policy engine. Every filtering decision is recorded with a content-addressed digest, so you can show the model was handed only authorized data.
+
+- Documents carry ACL metadata: a `{ relation, object }` entry, or `relation:object` tag strings.
+- Policy is either raw PCA predicates or an OpenFGA / Zanzibar model plus tuples (compiled through `@atlasauth/pca-policy-bridge`, including relation closures such as "viewer from parent").
+- **Fails closed**: a document is admitted only when a permit predicate matches and no deny matches. No ACL, an unresolved relation, a malformed document, or an incomplete policy translation drops the document.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-rag
+```
+
+Depends on `@atlasauth/pca` and `@atlasauth/pca-policy-bridge`.
+
+## Usage
+
+```ts
+import { filterDocuments, withPcaFilter } from '@atlasauth/pca-rag';
+
+const policy = { openfga: { model, tuples } }; // OpenFGA authorization model + relationship tuples
+
+const candidates = [
+  { id: 'readme', text: '...', acl: { relation: 'can_view', object: 'document:readme' } },
+  { id: 'spec', text: '...', tags: ['can_view:document:spec'] },
+];
+
+const { documents, decision } = filterDocuments('user:alice', candidates, policy);
+decision.allowedIds; // ids the model may see
+decision.droppedIds; // ids dropped, with a reason per document in decision.decisions
+decision.digest;     // b64u commitment to the decision set, bindable into a receipt or proof
+
+// Or wrap any retriever so results are filtered before they reach the model:
+const safe = withPcaFilter(retriever, 'user:alice', policy); // retriever.retrieve(query, k)
+const docs = await safe.retrieve('how do I deploy?');
+safe.lastDecision(); // audit trail for the last call
+```
+
+Compile once with `compilePolicy(policy)` and reuse the result to avoid recompiling per call. To derive the principal from a verified PCActn, use `principalFromPCActn(pcactn, { id })`.
+
+## API
+
+- `filterDocuments(principal, candidates, policy, opts?)` returns `{ documents, decision }`
+- `withPcaFilter(retriever, principal, policy, opts?)` generic retriever wrapper
+- `withLangChainPcaFilter(...)`, `withLlamaIndexPcaFilter(...)` structural adapters for LangChain and LlamaIndex retrievers (no dependency on either library)
+- `compilePolicy`, `aclsFromMetadata`, `principalFromPCActn`
+
+## Status
+
+Part of [Proof-Carrying Authority](https://github.com/Atlas-Authorization/pca). This filters retrieval results; it does not control what a model does with documents it is allowed to see. PCA's cryptography has not been independently audited.
+
+## License
+
+MIT - see LICENSE

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+/**
+ * @atlasauth/pca-rag — FGA-for-RAG.
+ *
+ * Retrieval-time, per-principal document filtering driven by the PCA policy engine. Given a
+ * principal (or a verified PCActn's holder), a candidate set of documents that each carry ACL
+ * metadata (a `{ relation, object }` ACL entry, or `relation:object` tags), and a policy (raw PCA
+ * predicates, or an imported OpenFGA/Zanzibar ReBAC model+tuples), this returns ONLY the documents
+ * the principal may see — deciding every candidate through the core evaluator / `member_of` relation
+ * closure in `@atlasauth/pca`, and reusing `@atlasauth/pca-policy-bridge` to compile ReBAC relation
+ * checks into PCA predicates.
+ *
+ * Two properties make this suitable for the PCA proof trace:
+ *   1. FAIL CLOSED. A document is admitted ONLY when a permit predicate cleanly matches (verb =
+ *      relation, resource = object, every `where` condition `true`) and no deny predicate matches.
+ *      Anything unknown — no ACL, an unresolved relation, a malformed document, an incomplete policy
+ *      translation — drops the document. The model can never see an unauthorized chunk.
+ *   2. AUDITABLE. Every decision is captured in a {@link FilterDecision}: which documents passed,
+ *      which were dropped and why, the exact permit predicate that authorized each one, and a
+ *      content-addressed `digest` of the whole decision set that can be bound into a receipt / proof.
+ *
+ * Decisions use the SAME evaluator the adjudicator uses, so "what the retriever filtered" and "what
+ * the authority system would admit" cannot drift apart.
+ */
+import type { PCActn, Predicate } from '@atlasauth/pca';
+import { type TranslationReport } from '@atlasauth/pca-policy-bridge';
+/**
+ * The retrieval principal. `id` is matched against the policy's subject (`subject.id` in a PCA
+ * predicate, the `user` of an OpenFGA tuple). `attributes` are exposed to policy conditions as
+ * `subject.*`; `env` is exposed as `env.*` (e.g. a group-adjacency map a `member_of` condition's
+ * `collection` resolves against).
+ */
+export interface Principal {
+    id: string;
+    attributes?: Record<string, unknown>;
+    env?: Record<string, unknown>;
+}
+/** A principal, or just its id (shorthand for `{ id }`). */
+export type PrincipalInput = Principal | string;
+/**
+ * Derive a {@link Principal} from a (already verified) PCActn: the acting identity is the LEAF
+ * capability holder — the key the action was ultimately delegated to. Pass `opts.id` to map that
+ * holder key to the identity your policy is keyed on (e.g. an OpenFGA `user:alice`); it defaults to
+ * the raw leaf-holder key. Throws on a PCActn with no capability chain (a malformed / unverified
+ * object), rather than silently producing an empty principal.
+ */
+export declare function principalFromPCActn(p: Pick<PCActn, 'cap_chain'>, opts?: {
+    id?: string;
+    attributes?: Record<string, unknown>;
+    env?: Record<string, unknown>;
+}): Principal;
+/** One ACL entry: the principal must hold `relation` on `object` (an OpenFGA relation check). */
+export interface DocAcl {
+    relation: string;
+    object: string;
+}
+/**
+ * The minimal document shape the default extractor understands: a stable `id`, plus ACL metadata as
+ * an `acl` entry (single or list) and/or `relation:object` tag strings. A document needs AT LEAST ONE
+ * decidable ACL entry (via `acl` or `tags`) to be admissible — one with none fails closed.
+ */
+export interface AclDocument {
+    id: string;
+    acl?: DocAcl | DocAcl[];
+    tags?: string[];
+    [k: string]: unknown;
+}
+/** Collect ACL entries from freeform `acl` + `tags` metadata (both `unknown`; proto-safe narrowing). */
+export declare function aclsFromMetadata(acl: unknown, tags: unknown): DocAcl[];
+/**
+ * A policy for the filter. One of:
+ *   - a bare `Predicate[]` (raw PCA permits);
+ *   - `{ openfga: { model, tuples } }` — an OpenFGA/Zanzibar authorization model + relationship
+ *     tuples, compiled via {@link openfgaToPca} (relation closures — computedUserset, union,
+ *     intersection, difference, tupleToUserset — are resolved into concrete permits);
+ *   - `{ predicates, denies?, report? }` — an envelope-shaped result (e.g. a bridge `BridgeResult`),
+ *     where `denies` is applied with deny-overrides-permit semantics.
+ */
+export type PolicyInput = Predicate[] | {
+    openfga: {
+        model: unknown;
+        tuples: unknown;
+    };
+} | {
+    predicates: Predicate[];
+    denies?: Predicate[];
+    report?: TranslationReport;
+};
+/**
+ * A compiled policy: a permit list, a deny list and whether the source translation was INCOMPLETE
+ * (a non-empty `report.errors` — in which case the whole policy fails closed and nothing is admitted).
+ * Compile once with {@link compilePolicy} and reuse across retrievals to avoid recompiling per call.
+ */
+export interface CompiledPolicy {
+    readonly predicates: Predicate[];
+    readonly denies: Predicate[];
+    readonly incomplete: boolean;
+    readonly report?: TranslationReport;
+}
+/** Compile any {@link PolicyInput} (or pass through an already-{@link CompiledPolicy}). */
+export declare function compilePolicy(policy: PolicyInput | CompiledPolicy): CompiledPolicy;
+/** Per-document decision — the auditable record of why one candidate passed or was dropped. */
+export interface DocDecision {
+    id: string;
+    allowed: boolean;
+    /** The ACL entry that granted access (present only when `allowed`). */
+    via?: DocAcl;
+    /** The exact permit predicate that matched (proof: which grant authorized this document). */
+    matched?: Predicate;
+    /** Human-readable reason — the fail-closed cause for a drop, or the grant for an allow. */
+    reason: string;
+}
+/**
+ * The full decision for a filter run — suitable to attach to a PCA proof / receipt. `digest` is a
+ * content-addressed commitment to the decision (principal + the admitted/dropped id sets), so a
+ * verifier can confirm the model was handed exactly these documents and no others.
+ */
+export interface FilterDecision {
+    principal: string;
+    considered: number;
+    /** IDs admitted (the model may see these), in candidate order. */
+    allowedIds: string[];
+    /** IDs dropped (not authorized / unknown — fail closed), in candidate order. */
+    droppedIds: string[];
+    /** One record per candidate. */
+    decisions: DocDecision[];
+    /** True when the policy translation was incomplete → every candidate fails closed. */
+    policyIncomplete: boolean;
+    /** The policy-translation report, when the policy was imported (OpenFGA). */
+    report?: TranslationReport;
+    /** b64u content-address of this decision set (binds into the proof trace). */
+    digest: string;
+}
+/** Result of {@link filterDocuments}: the admitted documents plus the {@link FilterDecision}. */
+export interface FilterResult<D> {
+    documents: D[];
+    decision: FilterDecision;
+}
+/** Options controlling how ACL metadata is read from a document. */
+export interface FilterOptions<D extends AclDocument> {
+    /** Stable id for a document (default: `doc.id`, else a positional `doc#<index>`). */
+    getId?: (doc: D, index: number) => string;
+    /** ACL entries for a document (default: `doc.acl` + `relation:object` `doc.tags`). */
+    getAcls?: (doc: D) => DocAcl[];
+}
+/**
+ * Filter a candidate set to the documents `principal` may see under `policy`. Returns the admitted
+ * documents (in candidate order) and a {@link FilterDecision} proof trace. FAILS CLOSED: a document
+ * is admitted only when a permit predicate cleanly matches one of its ACL entries and no deny matches;
+ * anything unknown is dropped.
+ */
+export declare function filterDocuments<D extends AclDocument>(principal: PrincipalInput, candidates: D[], policy: PolicyInput | CompiledPolicy, opts?: FilterOptions<D>): FilterResult<D>;
+/** A generic retriever: returns candidate documents for a query. */
+export interface RagRetriever<D extends AclDocument = AclDocument> {
+    retrieve(query: string, k?: number): Promise<D[]> | D[];
+}
+/** A retriever whose results are PCA-filtered before they reach the model. */
+export interface FilteredRetriever<D extends AclDocument = AclDocument> {
+    retrieve(query: string, k?: number): Promise<D[]>;
+    /** The decision from the most recent `retrieve` (the proof trace), or `undefined` if none yet. */
+    lastDecision(): FilterDecision | undefined;
+}
+/**
+ * Wrap a generic {@link RagRetriever} so every result set is filtered to what `principal` may see
+ * BEFORE it reaches the model. The wrapper exposes the same `retrieve` plus `lastDecision()` for audit.
+ */
+export declare function withPcaFilter<D extends AclDocument>(retriever: RagRetriever<D>, principal: PrincipalInput, policy: PolicyInput | CompiledPolicy, opts?: FilterOptions<D>): FilteredRetriever<D>;
+/** Minimal structural shape of a LangChain `Document` (we never import `@langchain/*`). */
+export interface LangChainDocumentLike {
+    pageContent: string;
+    metadata?: Record<string, unknown>;
+}
+/** Minimal structural shape of a LangChain retriever (`invoke` or the older `getRelevantDocuments`). */
+export interface LangChainRetrieverLike<D extends LangChainDocumentLike = LangChainDocumentLike> {
+    invoke?(input: string): Promise<D[]> | D[];
+    getRelevantDocuments?(query: string): Promise<D[]> | D[];
+}
+/** How to read ACL metadata off a LangChain document (defaults read `metadata.acl` + `metadata.tags`). */
+export interface LangChainAdapterOptions<D extends LangChainDocumentLike = LangChainDocumentLike> {
+    getId?: (doc: D, index: number) => string;
+    getAcls?: (doc: D) => DocAcl[];
+}
+/** A LangChain-shaped retriever whose results are PCA-filtered post-retrieval. */
+export interface FilteredLangChainRetriever<D extends LangChainDocumentLike = LangChainDocumentLike> {
+    invoke(input: string): Promise<D[]>;
+    getRelevantDocuments(query: string): Promise<D[]>;
+    lastDecision(): FilterDecision | undefined;
+}
+/**
+ * Wrap a LangChain-shaped retriever. Results are filtered post-retrieval (before they reach the
+ * model); ACLs are read from each document's `metadata` by default. The underlying retriever is
+ * called via `invoke` when present, else `getRelevantDocuments`.
+ */
+export declare function withLangChainPcaFilter<D extends LangChainDocumentLike>(retriever: LangChainRetrieverLike<D>, principal: PrincipalInput, policy: PolicyInput | CompiledPolicy, opts?: LangChainAdapterOptions<D>): FilteredLangChainRetriever<D>;
+/** Minimal structural shape of a LlamaIndex node. */
+export interface LlamaIndexNodeLike {
+    id_?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Minimal structural shape of a LlamaIndex `NodeWithScore`. */
+export interface LlamaIndexNodeWithScoreLike<N extends LlamaIndexNodeLike = LlamaIndexNodeLike> {
+    node: N;
+    score?: number;
+}
+/** Minimal structural shape of a LlamaIndex retriever. */
+export interface LlamaIndexRetrieverLike<N extends LlamaIndexNodeLike = LlamaIndexNodeLike> {
+    retrieve(params: {
+        query: string;
+    } | string): Promise<Array<LlamaIndexNodeWithScoreLike<N>>> | Array<LlamaIndexNodeWithScoreLike<N>>;
+}
+/** How to read ACL metadata off a LlamaIndex node (defaults read `node.metadata.acl` + `.tags`). */
+export interface LlamaIndexAdapterOptions<N extends LlamaIndexNodeLike = LlamaIndexNodeLike> {
+    getId?: (item: LlamaIndexNodeWithScoreLike<N>, index: number) => string;
+    getAcls?: (item: LlamaIndexNodeWithScoreLike<N>) => DocAcl[];
+}
+/** A LlamaIndex-shaped retriever whose results are PCA-filtered post-retrieval. */
+export interface FilteredLlamaIndexRetriever<N extends LlamaIndexNodeLike = LlamaIndexNodeLike> {
+    retrieve(params: {
+        query: string;
+    } | string): Promise<Array<LlamaIndexNodeWithScoreLike<N>>>;
+    lastDecision(): FilterDecision | undefined;
+}
+/**
+ * Wrap a LlamaIndex-shaped retriever. The returned `NodeWithScore[]` is filtered post-retrieval
+ * (before it reaches the model); ACLs are read from each node's `metadata` by default.
+ */
+export declare function withLlamaIndexPcaFilter<N extends LlamaIndexNodeLike>(retriever: LlamaIndexRetrieverLike<N>, principal: PrincipalInput, policy: PolicyInput | CompiledPolicy, opts?: LlamaIndexAdapterOptions<N>): FilteredLlamaIndexRetriever<N>;

package/dist/index.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * @atlasauth/pca-rag — FGA-for-RAG.
+ *
+ * Retrieval-time, per-principal document filtering driven by the PCA policy engine. Given a
+ * principal (or a verified PCActn's holder), a candidate set of documents that each carry ACL
+ * metadata (a `{ relation, object }` ACL entry, or `relation:object` tags), and a policy (raw PCA
+ * predicates, or an imported OpenFGA/Zanzibar ReBAC model+tuples), this returns ONLY the documents
+ * the principal may see — deciding every candidate through the core evaluator / `member_of` relation
+ * closure in `@atlasauth/pca`, and reusing `@atlasauth/pca-policy-bridge` to compile ReBAC relation
+ * checks into PCA predicates.
+ *
+ * Two properties make this suitable for the PCA proof trace:
+ *   1. FAIL CLOSED. A document is admitted ONLY when a permit predicate cleanly matches (verb =
+ *      relation, resource = object, every `where` condition `true`) and no deny predicate matches.
+ *      Anything unknown — no ACL, an unresolved relation, a malformed document, an incomplete policy
+ *      translation — drops the document. The model can never see an unauthorized chunk.
+ *   2. AUDITABLE. Every decision is captured in a {@link FilterDecision}: which documents passed,
+ *      which were dropped and why, the exact permit predicate that authorized each one, and a
+ *      content-addressed `digest` of the whole decision set that can be bound into a receipt / proof.
+ *
+ * Decisions use the SAME evaluator the adjudicator uses, so "what the retriever filtered" and "what
+ * the authority system would admit" cannot drift apart.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.principalFromPCActn = principalFromPCActn;
+exports.aclsFromMetadata = aclsFromMetadata;
+exports.compilePolicy = compilePolicy;
+exports.filterDocuments = filterDocuments;
+exports.withPcaFilter = withPcaFilter;
+exports.withLangChainPcaFilter = withLangChainPcaFilter;
+exports.withLlamaIndexPcaFilter = withLlamaIndexPcaFilter;
+const pca_1 = require("@atlasauth/pca");
+const pca_policy_bridge_1 = require("@atlasauth/pca-policy-bridge");
+function toPrincipal(p) {
+    return typeof p === 'string' ? { id: p } : p;
+}
+/**
+ * Derive a {@link Principal} from a (already verified) PCActn: the acting identity is the LEAF
+ * capability holder — the key the action was ultimately delegated to. Pass `opts.id` to map that
+ * holder key to the identity your policy is keyed on (e.g. an OpenFGA `user:alice`); it defaults to
+ * the raw leaf-holder key. Throws on a PCActn with no capability chain (a malformed / unverified
+ * object), rather than silently producing an empty principal.
+ */
+function principalFromPCActn(p, opts) {
+    const chain = Array.isArray(p?.cap_chain) ? p.cap_chain : [];
+    const leaf = chain.at(-1);
+    if (!leaf || typeof leaf.holder !== 'string' || leaf.holder.length === 0) {
+        throw new TypeError('principalFromPCActn: PCActn has no leaf capability holder');
+    }
+    const principal = { id: opts?.id ?? leaf.holder };
+    if (opts?.attributes !== undefined)
+        principal.attributes = opts.attributes;
+    if (opts?.env !== undefined)
+        principal.env = opts.env;
+    return principal;
+}
+function isDocAcl(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    const rel = v.relation;
+    const obj = v.object;
+    return typeof rel === 'string' && rel.length > 0 && typeof obj === 'string' && obj.length > 0;
+}
+function aclArray(acl) {
+    if (Array.isArray(acl))
+        return acl.filter(isDocAcl);
+    return isDocAcl(acl) ? [acl] : [];
+}
+/** A `relation:object` tag → an ACL entry. The split is at the FIRST ':' so an object id may itself
+ *  contain ':' (e.g. `viewer:document:readme` → relation `viewer`, object `document:readme`). */
+function tagToAcl(tag) {
+    if (typeof tag !== 'string')
+        return null;
+    const i = tag.indexOf(':');
+    if (i <= 0 || i >= tag.length - 1)
+        return null;
+    return { relation: tag.slice(0, i), object: tag.slice(i + 1) };
+}
+/** Collect ACL entries from freeform `acl` + `tags` metadata (both `unknown`; proto-safe narrowing). */
+function aclsFromMetadata(acl, tags) {
+    const out = aclArray(acl);
+    if (Array.isArray(tags)) {
+        for (const t of tags) {
+            const a = tagToAcl(t);
+            if (a !== null)
+                out.push(a);
+        }
+    }
+    return out;
+}
+function isCompiledPolicy(p) {
+    return (p !== null &&
+        typeof p === 'object' &&
+        !Array.isArray(p) &&
+        'incomplete' in p &&
+        typeof p.incomplete === 'boolean');
+}
+/** Compile any {@link PolicyInput} (or pass through an already-{@link CompiledPolicy}). */
+function compilePolicy(policy) {
+    if (isCompiledPolicy(policy))
+        return policy;
+    if (Array.isArray(policy))
+        return { predicates: policy, denies: [], incomplete: false };
+    if ('openfga' in policy) {
+        const br = (0, pca_policy_bridge_1.openfgaToPca)(policy.openfga.model, policy.openfga.tuples);
+        return {
+            predicates: br.predicates,
+            denies: br.denies,
+            report: br.report,
+            incomplete: br.report.errors.length > 0,
+        };
+    }
+    const predicates = Array.isArray(policy.predicates) ? policy.predicates : [];
+    const denies = Array.isArray(policy.denies) ? policy.denies : [];
+    const report = policy.report;
+    return { predicates, denies, report, incomplete: report !== undefined && report.errors.length > 0 };
+}
+/** Build the evaluation context for checking ONE ACL entry for a principal. */
+function buildContext(principal, acl) {
+    const subject = { ...(principal.attributes ?? {}), id: principal.id };
+    const ctx = {
+        action: { verb: acl.relation, resource: acl.object },
+        subject,
+    };
+    if (principal.env !== undefined)
+        ctx.env = principal.env;
+    return ctx;
+}
+/** Decide a single document. Returns the per-document record; `allowed` governs admission. */
+function decideDocument(id, acls, principal, compiled) {
+    if (compiled.incomplete) {
+        return { id, allowed: false, reason: 'policy translation incomplete (fail closed)' };
+    }
+    if (acls.length === 0) {
+        return { id, allowed: false, reason: 'no decidable ACL metadata (fail closed)' };
+    }
+    let lastReason = 'no relation grants access (fail closed)';
+    for (const acl of acls) {
+        let res;
+        try {
+            res = (0, pca_policy_bridge_1.decide)({ predicates: compiled.predicates, denies: compiled.denies }, buildContext(principal, acl));
+        }
+        catch {
+            lastReason = 'evaluator error (fail closed)';
+            continue;
+        }
+        if (res.allowed) {
+            const d = {
+                id,
+                allowed: true,
+                via: acl,
+                reason: `granted: ${principal.id} has ${acl.relation} on ${acl.object}`,
+            };
+            if (res.matched !== undefined)
+                d.matched = res.matched;
+            return d;
+        }
+        if (res.reason !== undefined)
+            lastReason = res.reason;
+    }
+    return { id, allowed: false, reason: lastReason };
+}
+function runFilter(principalInput, candidates, policyInput, ex) {
+    const principal = toPrincipal(principalInput);
+    const compiled = compilePolicy(policyInput);
+    const list = Array.isArray(candidates) ? candidates : [];
+    const documents = [];
+    const decisions = [];
+    const allowedIds = [];
+    const droppedIds = [];
+    for (let i = 0; i < list.length; i++) {
+        const doc = list[i];
+        let id;
+        let acls;
+        try {
+            id = ex.id(doc, i);
+            acls = ex.acls(doc);
+        }
+        catch {
+            // A document whose metadata cannot even be read is unknown → fail closed.
+            const fid = `doc#${i}`;
+            decisions.push({ id: fid, allowed: false, reason: 'unreadable document metadata (fail closed)' });
+            droppedIds.push(fid);
+            continue;
+        }
+        if (typeof id !== 'string' || id.length === 0)
+            id = `doc#${i}`;
+        const decision = decideDocument(id, acls, principal, compiled);
+        decisions.push(decision);
+        if (decision.allowed) {
+            documents.push(doc);
+            allowedIds.push(id);
+        }
+        else {
+            droppedIds.push(id);
+        }
+    }
+    const base = {
+        principal: principal.id,
+        considered: list.length,
+        allowedIds,
+        droppedIds,
+        policyIncomplete: compiled.incomplete,
+    };
+    const digest = (0, pca_1.hashCanonical)({ v: 1, kind: 'pca-rag/filter', ...base });
+    const decision = { ...base, decisions, digest };
+    if (compiled.report !== undefined)
+        decision.report = compiled.report;
+    return { documents, decision };
+}
+/**
+ * Filter a candidate set to the documents `principal` may see under `policy`. Returns the admitted
+ * documents (in candidate order) and a {@link FilterDecision} proof trace. FAILS CLOSED: a document
+ * is admitted only when a permit predicate cleanly matches one of its ACL entries and no deny matches;
+ * anything unknown is dropped.
+ */
+function filterDocuments(principal, candidates, policy, opts) {
+    const ex = {
+        id: opts?.getId ?? ((doc) => doc.id),
+        acls: opts?.getAcls ?? ((doc) => aclsFromMetadata(doc.acl, doc.tags)),
+    };
+    return runFilter(principal, candidates, policy, ex);
+}
+/**
+ * Wrap a generic {@link RagRetriever} so every result set is filtered to what `principal` may see
+ * BEFORE it reaches the model. The wrapper exposes the same `retrieve` plus `lastDecision()` for audit.
+ */
+function withPcaFilter(retriever, principal, policy, opts) {
+    const compiled = compilePolicy(policy);
+    let last;
+    return {
+        async retrieve(query, k) {
+            const docs = await retriever.retrieve(query, k);
+            const res = filterDocuments(principal, Array.isArray(docs) ? docs : [], compiled, opts);
+            last = res.decision;
+            return res.documents;
+        },
+        lastDecision() {
+            return last;
+        },
+    };
+}
+// ---- framework-shaped adapters (structural, optional-peer; no heavy deps imported) ---------------
+function metaString(meta, key) {
+    if (meta === undefined || meta === null)
+        return undefined;
+    const v = meta[key];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/**
+ * Wrap a LangChain-shaped retriever. Results are filtered post-retrieval (before they reach the
+ * model); ACLs are read from each document's `metadata` by default. The underlying retriever is
+ * called via `invoke` when present, else `getRelevantDocuments`.
+ */
+function withLangChainPcaFilter(retriever, principal, policy, opts) {
+    const compiled = compilePolicy(policy);
+    let last;
+    const ex = {
+        id: opts?.getId ?? ((doc, i) => metaString(doc.metadata, 'id') ?? metaString(doc.metadata, 'source') ?? `doc#${i}`),
+        acls: opts?.getAcls ?? ((doc) => aclsFromMetadata(doc.metadata?.['acl'], doc.metadata?.['tags'])),
+    };
+    const fetch = async (input) => {
+        if (typeof retriever.invoke === 'function')
+            return await retriever.invoke(input);
+        if (typeof retriever.getRelevantDocuments === 'function')
+            return await retriever.getRelevantDocuments(input);
+        throw new TypeError('withLangChainPcaFilter: retriever has neither invoke nor getRelevantDocuments');
+    };
+    const run = async (input) => {
+        const docs = await fetch(input);
+        const res = runFilter(principal, Array.isArray(docs) ? docs : [], compiled, ex);
+        last = res.decision;
+        return res.documents;
+    };
+    return {
+        invoke: run,
+        getRelevantDocuments: run,
+        lastDecision: () => last,
+    };
+}
+/**
+ * Wrap a LlamaIndex-shaped retriever. The returned `NodeWithScore[]` is filtered post-retrieval
+ * (before it reaches the model); ACLs are read from each node's `metadata` by default.
+ */
+function withLlamaIndexPcaFilter(retriever, principal, policy, opts) {
+    const compiled = compilePolicy(policy);
+    let last;
+    const ex = {
+        id: opts?.getId ??
+            ((item, i) => (typeof item.node?.id_ === 'string' && item.node.id_.length > 0 ? item.node.id_ : undefined) ??
+                metaString(item.node?.metadata, 'id') ??
+                `node#${i}`),
+        acls: opts?.getAcls ??
+            ((item) => aclsFromMetadata(item.node?.metadata?.['acl'], item.node?.metadata?.['tags'])),
+    };
+    return {
+        async retrieve(params) {
+            const items = await retriever.retrieve(params);
+            const res = runFilter(principal, Array.isArray(items) ? items : [], compiled, ex);
+            last = res.decision;
+            return res.documents;
+        },
+        lastDecision: () => last,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@atlasauth/pca-rag",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "FGA-for-RAG for PCA: retrieval-time, per-principal document filtering driven by the PCA policy engine, with the filtering decision captured in the proof trace (provable: the model only saw authorized data).",
+  "keywords": [
+    "rag",
+    "retrieval",
+    "document filtering",
+    "fine-grained authorization",
+    "agent authorization",
+    "proof-carrying authority",
+    "pca",
+    "ai agents"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Atlas-Authorization/pca#readme",
+  "bugs": {
+    "url": "https://github.com/Atlas-Authorization/pca/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atlas-Authorization/pca.git",
+    "directory": "packages/pca-rag"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@atlasauth/pca": "0.2.0",
+    "@atlasauth/pca-policy-bridge": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }