@kindgi/authz 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kindgi Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,67 @@
-# @kindgi/authz
+# `@kindgi/authz`
 
-A placeholder. Releases come from https://github.com/kindgi/kindgi-sdk.
+Public authorization shape for Kindgi™: the vocabulary and interfaces that callers, policy enforcement points (PEPs) and policy executors share. Object types, actions and relation names follow an OpenFGA-style model; the FGA store and the check implementation are supplied by the deployment. [`@kindgi/api`](../api/) uses these types in its middleware and bindings.
+
+## Purpose
+
+Give every enforcement site one vocabulary — which object types exist, which actions apply to each, how an action maps to an FGA relation, who the caller is — so a check means the same thing in every layer. The package is types and pure functions only; it holds no runtime state.
+
+## Exports
+
+- **Vocabulary** — `OBJECT_TYPES` / `ObjectType`, `ACTIONS` / `Action`, `ACTION_TO_RELATION` (e.g. `read` → `can_read`), `OBJECT_ACTIONS` (the actions meaningful per object type, so a PEP can reject `rotate` on an agent before calling FGA), `ResourceRef`, `resourceKey(ref)`, `ref(type, id)`.
+- **Principals** — `Principal` (`actor`, optional `onBehalfOf`, optional `scope`), `PrincipalRef`, `PrincipalKind` (`user`, `agent`, `service_account`, `system`), `DownscopedPermissions` (`allowedActions` / `deniedActions`).
+  - `userPrincipal`, `systemPrincipal`, `serviceAccountPrincipal`, `delegate(actor, onBehalfOf, scope?)` (throws on cross-tenant delegation), `downscope(principal, scope)`.
+  - `fgaSubject(ref)` — the FGA subject string for a principal; `system` maps to `user:system`.
+- **PEP helpers** — `principalFromToken(token)` (a `userId` gives a user principal, else a `tokenId` gives a service-account principal, else it throws), `TokenLike`, `denyPayload(action, type, id, reason)` / `DenyPayload` (the structured 403 body, `code: 'permission-denied'`).
+- **Decisions** — `AuthzCheckBinding` with `check(principal, action, resource, ctx?)` and `checkBatch(...)`, `AuthzCheckContext` (`correlationId`, `runId`), and `Decision` (`allowed`, `reason`, `failing`, `evidence`). The effective permission is the intersection of actor, `onBehalfOf` and `scope`.
+- **Tuples** — `TupleIntent` and `TupleEnqueueHook` (the hook every content and config binding calls inside its write transaction).
+  - `tuplesForCreate(entity, creatorUserId?)` / `tuplesForDelete(entity)` over `EntityRef`; `tuplesForDelete` removes only the parent / scope tuple.
+  - Subject and object helpers (`userSubject`, `teamMemberSubject`, `tenantObject` … `runObject`, `scopeSubject`) and the tuple-side `Scope`.
+  - Membership and grants: `teamMembershipTuple`, `projectMembershipTuple`, `teamProjectGrantTuple` (`TeamRole`, `ProjectRole`), `machineAccessTuple` for `agent` / `service_account` subjects (`MachineSubject`, `AgentAccessResource`), and its agent shorthand `agentAccessTuple`.
+- **Reviewer roles** — `ReviewerRole` (`standard`, `senior`, `admin`) and `REVIEWER_ROLE_RANK`, where a higher rank covers the lower ones.
+
+## Example
+
+```ts
+import {
+  type AuthzCheckBinding,
+  type TupleEnqueueHook,
+  denyPayload,
+  principalFromToken,
+  ref,
+  tuplesForCreate,
+} from '@kindgi/authz';
+import type { ProjectId, TenantId, UserId } from '@kindgi/types';
+
+const tenantId = 'acme' as TenantId;
+const creator = 'user-1' as UserId;
+const principal = principalFromToken({ tenantId, userId: creator });
+
+// A project binding calls this inside its write transaction with the new row id:
+// a `parent` tuple (tenant:acme → project) plus an `owner` tuple for the creator.
+const enqueueTuples: TupleEnqueueHook = (rowId) =>
+  tuplesForCreate({ kind: 'project', id: rowId as ProjectId, tenantId }, creator);
+
+// At a PEP: ask the decision point, and turn a deny into the structured 403 body.
+async function authorizeDelete(authz: AuthzCheckBinding, projectId: string) {
+  const decision = await authz.check(principal, 'delete', ref('project', projectId), {
+    correlationId: 'req-42',
+  });
+  return decision.allowed ? undefined : denyPayload('delete', 'project', projectId, decision.reason);
+}
+```
+
+## Non-goals
+
+- **The check implementation and the FGA store.** `AuthzCheckBinding` is an interface; the authorization model, the store and the worker that applies queued tuples are supplied by the deployment.
+- **HTTP middleware.** `principalFromToken` and `denyPayload` are framework-neutral; the Hono middleware lives in `@kindgi/api`.
+- **Cross-tenant delegation.** `delegate` throws when the actor and `onBehalfOf` belong to different tenants.
+
+## Related
+
+- [`@kindgi/api`](../api/) — the middleware, `TokenResolution`, and the bindings that call `TupleEnqueueHook`.
+- [`@kindgi/types`](../types/) — the branded ids used in `EntityRef` and `PrincipalRef`.
+
+## License
+
+Apache License 2.0 — see [LICENSE](./LICENSE).

package/dist/check.d.ts

@@ -0,0 +1,68 @@
+import type { Principal } from './principal.js';
+import type { Action, ObjectType, ResourceRef } from './types.js';
+export interface Decision {
+    readonly allowed: boolean;
+    readonly reason: string;
+    /**
+     * Which link in the (actor, onBehalfOf, scope) chain caused the deny.
+     * Undefined when `allowed = true`.
+     */
+    readonly failing?: 'actor' | 'onBehalfOf' | 'scope' | 'unbootstrapped' | 'invalid-action';
+    /**
+     * Structured evidence for audit + debugging.
+     */
+    readonly evidence: {
+        readonly action: Action;
+        readonly relation: string;
+        readonly resource: string;
+        readonly actorSubject: string;
+        readonly onBehalfOfSubject?: string;
+        readonly storeId?: string;
+    };
+}
+/**
+ * Convenience constructor for a `ResourceRef`. The type parameter
+ * checks `type` against `ObjectType` at the call site; the return type
+ * is plain `ResourceRef` (it does not narrow to the given type).
+ */
+export declare function ref<T extends ObjectType>(type: T, id: string): ResourceRef;
+/**
+ * Per-call correlation context for `AuthzCheckBinding` methods.
+ * Threaded so the emitted audit event carries the request-scoped
+ * ids that let operators trace a deny back to the HTTP request or
+ * run that produced it.
+ */
+export interface AuthzCheckContext {
+    /**
+     * Optional correlation id — e.g. the API request id from route
+     * middleware, or a run-scoped id. Attached to emitted audit events.
+     */
+    readonly correlationId?: string;
+    /**
+     * Optional run id — attached to emitted audit events when the check
+     * happens inside a run. Distinct from `correlationId` because the
+     * run id survives across HTTP requests (streamed responses, replays).
+     */
+    readonly runId?: string;
+}
+/**
+ * Policy Decision Point binding. Every enforcement site that wants
+ * to check authz (for example the @kindgi/api middleware) goes
+ * through this contract. The deployment supplies the implementation.
+ */
+export interface AuthzCheckBinding {
+    /**
+     * Applies the principal's downscope filter first (cheap, no FGA
+     * round-trip), then calls FGA check for the actor and (if
+     * delegated) the `onBehalfOf`. Returns a `Decision` — allowed
+     * iff every check passes.
+     */
+    check(principal: Principal, action: Action, resource: ResourceRef, ctx?: AuthzCheckContext): Promise<Decision>;
+    /**
+     * List-filtering primitive. Given a set of resources, returns
+     * `Decision`s in the same order — used by `filterByCan` at the
+     * API layer to strip rows a caller can't read.
+     */
+    checkBatch(principal: Principal, action: Action, resources: readonly ResourceRef[], ctx?: AuthzCheckContext): Promise<readonly Decision[]>;
+}
+//# sourceMappingURL=check.d.ts.map

package/dist/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAElE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,YAAY,GAAG,OAAO,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;IAC1F;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CAE1E;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,KAAK,CACH,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,WAAW,EACrB,GAAG,CAAC,EAAE,iBAAiB,GACtB,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB;;;;OAIG;IACH,UAAU,CACR,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,GAAG,CAAC,EAAE,iBAAiB,GACtB,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;CACjC"}

package/dist/check.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Convenience constructor for a `ResourceRef`. The type parameter
+ * checks `type` against `ObjectType` at the call site; the return type
+ * is plain `ResourceRef` (it does not narrow to the given type).
+ */
+export function ref(type, id) {
+    return { type, id };
+}
+//# sourceMappingURL=check.js.map

package/dist/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAmCjC;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAuB,IAAO,EAAE,EAAU;IAC3D,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AACtB,CAAC"}

package/dist/enqueue.d.ts

@@ -0,0 +1,28 @@
+export interface TupleIntent {
+    readonly operation: 'write' | 'delete';
+    /** FGA subject, e.g. `user:alice` or `team:eng#member`. */
+    readonly user: string;
+    /** FGA relation, e.g. `admin` | `parent` | `editor`. */
+    readonly relation: string;
+    /** FGA object, e.g. `project:foo`. */
+    readonly object: string;
+    /**
+     * Optional per-tenant idempotency key. If set, the outbox rejects a
+     * duplicate enqueue (same tenantId + dedupKey) — safe to retry the
+     * caller without producing double-tuples.
+     */
+    readonly dedupKey?: string;
+}
+/**
+ * Callback that produces the tuples for an entity mutation. Bindings
+ * call this INSIDE their write transaction with the freshly-inserted
+ * (or freshly-resolved, for deletes) entity row's primary key. The
+ * binding then enqueues the returned intents in the same transaction.
+ *
+ * REQUIRED on every content + config binding's write methods. An
+ * optional hook would silently split the contract into "writes tuples"
+ * vs. "doesn't write tuples" impls — exactly the split-brain that makes
+ * PEP unreliable.
+ */
+export type TupleEnqueueHook = (entityRowId: string) => readonly TupleIntent[];
+//# sourceMappingURL=enqueue.d.ts.map

package/dist/enqueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enqueue.d.ts","sourceRoot":"","sources":["../src/enqueue.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC;IACvC,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,SAAS,WAAW,EAAE,CAAC"}

package/dist/enqueue.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=enqueue.js.map

package/dist/enqueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enqueue.js","sourceRoot":"","sources":["../src/enqueue.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './principal.js';
+export * from './pep.js';
+export * from './tuples.js';
+export * from './enqueue.js';
+export * from './check.js';
+export * from './reviewer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export * from './types.js';
+export * from './principal.js';
+export * from './pep.js';
+export * from './tuples.js';
+export * from './enqueue.js';
+export * from './check.js';
+export * from './reviewer.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}

package/dist/pep.d.ts

@@ -0,0 +1,46 @@
+import type { TenantId, UserId } from '@kindgi/types';
+import type { Action, ObjectType } from '@kindgi/authz';
+import { type Principal } from './principal.js';
+/**
+ * Subset of `TokenResolution` (`@kindgi/api`) that principal construction
+ * actually needs. Any bearer/session middleware can adapt its shape
+ * to this before calling `principalFromToken`.
+ */
+export interface TokenLike {
+    readonly tenantId: TenantId;
+    readonly userId?: UserId;
+    /**
+     * Stable id for a capability-only bearer (service account). When
+     * the token carries no `userId`, this becomes the actor id.
+     * Deployments typically hash the token or use a token-record uuid.
+     */
+    readonly tokenId?: string;
+}
+/**
+ * Map a resolved token to a Principal.
+ *
+ * Priority:
+ *   1. userId present → userPrincipal (human session)
+ *   2. tokenId present → serviceAccountPrincipal (integration key)
+ *   3. Neither → throw (unauthenticated shouldn't reach the PEP)
+ *
+ * Delegation chains (agent-on-behalf-of-user) are constructed by
+ * the caller after this returns — the token itself is always a
+ * single principal.
+ */
+export declare function principalFromToken(token: TokenLike): Principal;
+/**
+ * Canonical 403 body shape. Structured so clients can distinguish
+ * "you didn't have permission" from "your input was invalid" —
+ * different remediation flows. Avoids leaking full evidence (that
+ * belongs in the audit trail); reason is a human-readable summary
+ * safe to return.
+ */
+export interface DenyPayload {
+    readonly code: 'permission-denied';
+    readonly action: Action;
+    readonly resource: string;
+    readonly reason: string;
+}
+export declare function denyPayload(action: Action, resourceType: ObjectType, resourceId: string, reason: string): DenyPayload;
+//# sourceMappingURL=pep.d.ts.map

package/dist/pep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pep.d.ts","sourceRoot":"","sources":["../src/pep.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EAAE,KAAK,SAAS,EAA0C,MAAM,gBAAgB,CAAC;AAExF;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAU9D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,UAAU,EACxB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,WAAW,CAOb"}

package/dist/pep.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { serviceAccountPrincipal, userPrincipal } from './principal.js';
+/**
+ * Map a resolved token to a Principal.
+ *
+ * Priority:
+ *   1. userId present → userPrincipal (human session)
+ *   2. tokenId present → serviceAccountPrincipal (integration key)
+ *   3. Neither → throw (unauthenticated shouldn't reach the PEP)
+ *
+ * Delegation chains (agent-on-behalf-of-user) are constructed by
+ * the caller after this returns — the token itself is always a
+ * single principal.
+ */
+export function principalFromToken(token) {
+    if (token.userId !== undefined) {
+        return userPrincipal(token.userId, token.tenantId);
+    }
+    if (token.tokenId !== undefined) {
+        return serviceAccountPrincipal(token.tokenId, token.tenantId);
+    }
+    throw new Error('principalFromToken: token has neither userId nor tokenId — bearer middleware should have rejected earlier');
+}
+export function denyPayload(action, resourceType, resourceId, reason) {
+    return {
+        code: 'permission-denied',
+        action,
+        resource: `${resourceType}:${resourceId}`,
+        reason,
+    };
+}
+//# sourceMappingURL=pep.js.map

package/dist/pep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pep.js","sourceRoot":"","sources":["../src/pep.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAiBjC,OAAO,EAAkB,uBAAuB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAkBxF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAgB;IACjD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,uBAAuB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,IAAI,KAAK,CACb,2GAA2G,CAC5G,CAAC;AACJ,CAAC;AAgBD,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,YAAwB,EACxB,UAAkB,EAClB,MAAc;IAEd,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,MAAM;QACN,QAAQ,EAAE,GAAG,YAAY,IAAI,UAAU,EAAE;QACzC,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/principal.d.ts

@@ -0,0 +1,60 @@
+import type { TenantId } from '@kindgi/types';
+import type { Action } from '@kindgi/authz';
+export type PrincipalKind = 'user' | 'agent' | 'service_account' | 'system';
+export interface PrincipalRef {
+    readonly kind: PrincipalKind;
+    readonly id: string;
+    readonly tenantId: TenantId;
+}
+export interface DownscopedPermissions {
+    /**
+     * Whitelist. When set, only these actions are allowed regardless
+     * of what FGA says. Matches OAuth 2.0 scope-narrowing.
+     */
+    readonly allowedActions?: readonly Action[];
+    /**
+     * Blacklist. When set, these actions are denied even if FGA allows.
+     * Applied AFTER allowedActions.
+     */
+    readonly deniedActions?: readonly Action[];
+}
+export interface Principal {
+    readonly actor: PrincipalRef;
+    readonly onBehalfOf?: PrincipalRef;
+    readonly scope?: DownscopedPermissions;
+}
+export declare function userPrincipal(userId: string, tenantId: TenantId): Principal;
+export declare function systemPrincipal(tenantId: TenantId): Principal;
+/**
+ * Build a principal from a service-account token. `id` is typically
+ * the token id (or a stable identifier derived from it) so grants can
+ * be attached to a specific integration.
+ */
+export declare function serviceAccountPrincipal(serviceAccountId: string, tenantId: TenantId): Principal;
+/**
+ * Build a delegated principal: `actor` acting on behalf of `onBehalfOf`.
+ * Both must be in the same tenant (checked at construction; mismatches
+ * are configuration bugs, not runtime authz denials).
+ */
+export declare function delegate(actor: PrincipalRef, onBehalfOf: PrincipalRef, scope?: DownscopedPermissions): Principal;
+/**
+ * Narrow an existing principal's permissions further. Composable with
+ * delegation — an agent-on-behalf-of-user can be additionally scoped
+ * to read-only for a specific request.
+ */
+export declare function downscope(principal: Principal, scope: DownscopedPermissions): Principal;
+/**
+ * Return the FGA subject string for a PrincipalRef. This is the ONE
+ * place that decides how principal kinds map to FGA subjects.
+ *
+ * - `user`            → `user:${id}` (real user UUID)
+ * - `agent`           → `agent:${id}`
+ * - `service_account` → `service_account:${id}` (machine identity
+ *                       with narrow grants)
+ * - `system`          → `user:system` (service identity the tenant's
+ *                       setup grants tenant admin; with one FGA store
+ *                       per tenant the string never crosses tenant
+ *                       boundaries)
+ */
+export declare function fgaSubject(ref: PrincipalRef): string;
+//# sourceMappingURL=principal.d.ts.map

package/dist/principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.d.ts","sourceRoot":"","sources":["../src/principal.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAM5C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,iBAAiB,GAAG,QAAQ,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,qBAAqB,CAAC;CACxC;AAMD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAE3E;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,gBAAgB,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAE/F;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,YAAY,EACxB,KAAK,CAAC,EAAE,qBAAqB,GAC5B,SAAS,CAWX;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,qBAAqB,GAAG,SAAS,CAEvF;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAWpD"}