@kindgi/authz 0.1.8 → 0.1.9-rc.1

package/README.md

@@ -8,7 +8,7 @@ Give every enforcement site one vocabulary — which object types exist, which a
 
 ## 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)`.
+- **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), `CHECK_ONLY_ACTIONS` (actions a check may ask that `OBJECT_ACTIONS` doesn't list, so no permissions report names them: a project's `call` and `execute`), `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`.

package/dist/types.d.ts

@@ -1,9 +1,26 @@
-export declare const OBJECT_TYPES: readonly ["tenant", "org", "team", "project", "user", "agent", "flow", "tool", "guardrail", "eval_suite", "trigger", "conversation", "secret", "env", "mcp_endpoint", "run"];
+export declare const OBJECT_TYPES: readonly ["tenant", "org", "team", "project", "user", "service_account", "agent", "flow", "tool", "guardrail", "eval_suite", "trigger", "conversation", "secret", "env", "mcp_endpoint", "run"];
 export type ObjectType = (typeof OBJECT_TYPES)[number];
-export declare const ACTIONS: readonly ["read", "write", "delete", "admin", "execute", "invoke", "publish", "rotate", "fire", "cancel", "promote"];
+export declare const ACTIONS: readonly ["read", "write", "delete", "admin", "execute", "invoke", "publish", "rotate", "fire", "cancel", "promote", "act_as", "call"];
 export type Action = (typeof ACTIONS)[number];
 export declare const ACTION_TO_RELATION: Record<Action, string>;
 export declare const OBJECT_ACTIONS: Record<ObjectType, readonly Action[]>;
+/**
+ * Actions a check may ask of a type that `OBJECT_ACTIONS` doesn't list.
+ * The model defines them, but nothing reports them: `OBJECT_ACTIONS` is
+ * also the list a caller's permissions report and the role capabilities
+ * name per type (`RoleActions`), and clients validate that list, so an
+ * action added there is a change on the wire.
+ *
+ * A project's `call` and `execute` are what running an agent, a flow or
+ * an eval suite asks of the project the run is in, when the item is
+ * served by more than one project: `call` (an editor or a caller of the
+ * project) for an agent, `execute` (an editor or an executor) for a flow
+ * or a suite. They're the rights an item inherits from its project as
+ * `execute`, asked of the project itself.
+ */
+export declare const CHECK_ONLY_ACTIONS: Partial<Record<ObjectType, readonly Action[]>>;
+export declare const TENANT_GLOBAL_TYPES: readonly ["tenant", "org", "team", "user", "service_account"];
+export declare const PROJECT_SCOPED_TYPES: readonly ObjectType[];
 export interface ResourceRef {
     readonly type: ObjectType;
     readonly id: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,YAAY,8KAqBf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,OAAO,sHAYV,CAAC;AAEX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAYrD,CAAC;AAIF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAoBhE,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,YAAY,iMA0Bf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,OAAO,wIAiBV,CAAC;AAEX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAcrD,CAAC;AAIF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAwBhE,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC,CAE7E,CAAC;AAKF,eAAO,MAAM,mBAAmB,+DAAgE,CAAC;AAUjG,eAAO,MAAM,oBAAoB,EAAE,SAAS,UAAU,EAErD,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAEpD"}

package/dist/types.js

@@ -8,6 +8,8 @@
 //   - Action verb enum (application-facing vocabulary for PEP callers)
 //   - Action → computed-relation mapping (PEP → FGA check translation)
 //   - Object → allowed-actions catalog (guards against category errors)
+//   - Project-scoped type list (`PROJECT_SCOPED_TYPES`): the single source
+//     of truth for which types role capabilities and `my-access` report
 //
 // Consumers:
 //   - Principal construction (`principal.ts`) builds {actor, onBehalfOf?}
@@ -21,6 +23,11 @@ export const OBJECT_TYPES = [
     'team',
     'project',
     'user',
+    // A service account is a tenant-global, non-human identity, like `user`
+    // not granted through project roles. `act_as` on it is a tenant-admin
+    // delegation (naming it as a trigger's owner), never a project grant, so
+    // it is kept out of `PROJECT_SCOPED_TYPES` below.
+    'service_account',
     // Content (project-scoped, user-authored)
     'agent',
     'flow',
@@ -48,6 +55,11 @@ export const ACTIONS = [
     'fire',
     'cancel',
     'promote',
+    // Delegation: naming a principal as the one a trigger's runs act as.
+    'act_as',
+    // Running an agent in a project: asked of the project only
+    // (`CHECK_ONLY_ACTIONS`).
+    'call',
 ];
 export const ACTION_TO_RELATION = {
     read: 'can_read',
@@ -61,6 +73,8 @@ export const ACTION_TO_RELATION = {
     fire: 'can_fire',
     cancel: 'can_cancel',
     promote: 'can_promote',
+    act_as: 'can_act_as',
+    call: 'can_call',
 };
 // Which verbs are meaningful for which object types. A PEP uses this to
 // reject e.g. `rotate` on `agent:X` before calling FGA.
@@ -70,6 +84,10 @@ export const OBJECT_ACTIONS = {
     team: ['read', 'admin'],
     project: ['read', 'write', 'admin', 'delete'],
     user: [],
+    // Only `act_as`: a tenant admin may name this service account as a
+    // trigger's owner (so the trigger's runs act as it). No read/write/etc.
+    // here — the account's lifecycle is its binding's, not an authz object's.
+    service_account: ['act_as'],
     agent: ['read', 'write', 'delete', 'admin', 'execute', 'publish', 'promote'],
     flow: ['read', 'write', 'delete', 'admin', 'execute', 'publish'],
     tool: ['read', 'write', 'delete', 'admin', 'invoke'],
@@ -82,6 +100,36 @@ export const OBJECT_ACTIONS = {
     mcp_endpoint: ['read', 'write', 'delete', 'admin'],
     run: ['read', 'cancel', 'delete'],
 };
+/**
+ * Actions a check may ask of a type that `OBJECT_ACTIONS` doesn't list.
+ * The model defines them, but nothing reports them: `OBJECT_ACTIONS` is
+ * also the list a caller's permissions report and the role capabilities
+ * name per type (`RoleActions`), and clients validate that list, so an
+ * action added there is a change on the wire.
+ *
+ * A project's `call` and `execute` are what running an agent, a flow or
+ * an eval suite asks of the project the run is in, when the item is
+ * served by more than one project: `call` (an editor or a caller of the
+ * project) for an agent, `execute` (an editor or an executor) for a flow
+ * or a suite. They're the rights an item inherits from its project as
+ * `execute`, asked of the project itself.
+ */
+export const CHECK_ONLY_ACTIONS = {
+    project: ['call', 'execute'],
+};
+// Tenant-global identities and structural boundaries: object types that are
+// NOT granted through project roles. A service account is one of these — its
+// `act_as` is a tenant-admin delegation, not a project capability.
+export const TENANT_GLOBAL_TYPES = ['tenant', 'org', 'team', 'user', 'service_account'];
+// The object types reported per-type in role capabilities (the API's
+// `RoleActionsSchema` / `normalizeCapabilities`). ONE source of truth within
+// this SDK: every consumer here imports this list, so the capabilities wire
+// shape stays consistent. The runtime's `my-access` projection keeps its own
+// positively-written list for now and so CAN differ; the runtime change that
+// adds `service_account` switches that projection to import this list, after
+// which the two can't drift. Tenant-global types (`TENANT_GLOBAL_TYPES`) are
+// left out; new project-scoped content types are included automatically.
+export const PROJECT_SCOPED_TYPES = OBJECT_TYPES.filter((t) => !TENANT_GLOBAL_TYPES.includes(t));
 export function resourceKey(ref) {
     return `${ref.type}:${ref.id}`;
 }

package/dist/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/authz",
-  "version": "0.1.8",
+  "version": "0.1.9-rc.1",
   "description": "Kindgi™ authorization shape. The public vocabulary and interfaces of Kindgi's authorization stack: Action verbs (read/write/execute/…), ObjectType enum (agent/flow/tool/…), ResourceRef, Principal (who is calling, with delegation and downscoping), the AuthzCheckBinding decision-point interface and its Decision (allow/deny + reason), FGA tuple builders and the TupleEnqueueHook outbox contract, the 403 DenyPayload shape, and reviewer roles. Types and pure functions — no runtime state. The FGA store, the check implementation and the tuple worker are supplied by the deployment.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@kindgi/types": "0.1.8"
+    "@kindgi/types": "0.1.9-rc.1"
   },
   "engines": {
     "node": ">=22.12.0"

package/src/types.ts

@@ -9,6 +9,8 @@
 //   - Action verb enum (application-facing vocabulary for PEP callers)
 //   - Action → computed-relation mapping (PEP → FGA check translation)
 //   - Object → allowed-actions catalog (guards against category errors)
+//   - Project-scoped type list (`PROJECT_SCOPED_TYPES`): the single source
+//     of truth for which types role capabilities and `my-access` report
 //
 // Consumers:
 //   - Principal construction (`principal.ts`) builds {actor, onBehalfOf?}
@@ -23,6 +25,11 @@ export const OBJECT_TYPES = [
   'team',
   'project',
   'user',
+  // A service account is a tenant-global, non-human identity, like `user`
+  // not granted through project roles. `act_as` on it is a tenant-admin
+  // delegation (naming it as a trigger's owner), never a project grant, so
+  // it is kept out of `PROJECT_SCOPED_TYPES` below.
+  'service_account',
   // Content (project-scoped, user-authored)
   'agent',
   'flow',
@@ -53,6 +60,11 @@ export const ACTIONS = [
   'fire',
   'cancel',
   'promote',
+  // Delegation: naming a principal as the one a trigger's runs act as.
+  'act_as',
+  // Running an agent in a project: asked of the project only
+  // (`CHECK_ONLY_ACTIONS`).
+  'call',
 ] as const;
 
 export type Action = (typeof ACTIONS)[number];
@@ -69,6 +81,8 @@ export const ACTION_TO_RELATION: Record<Action, string> = {
   fire: 'can_fire',
   cancel: 'can_cancel',
   promote: 'can_promote',
+  act_as: 'can_act_as',
+  call: 'can_call',
 };
 
 // Which verbs are meaningful for which object types. A PEP uses this to
@@ -79,6 +93,10 @@ export const OBJECT_ACTIONS: Record<ObjectType, readonly Action[]> = {
   team: ['read', 'admin'],
   project: ['read', 'write', 'admin', 'delete'],
   user: [],
+  // Only `act_as`: a tenant admin may name this service account as a
+  // trigger's owner (so the trigger's runs act as it). No read/write/etc.
+  // here — the account's lifecycle is its binding's, not an authz object's.
+  service_account: ['act_as'],
 
   agent: ['read', 'write', 'delete', 'admin', 'execute', 'publish', 'promote'],
   flow: ['read', 'write', 'delete', 'admin', 'execute', 'publish'],
@@ -95,6 +113,41 @@ export const OBJECT_ACTIONS: Record<ObjectType, readonly Action[]> = {
   run: ['read', 'cancel', 'delete'],
 };
 
+/**
+ * Actions a check may ask of a type that `OBJECT_ACTIONS` doesn't list.
+ * The model defines them, but nothing reports them: `OBJECT_ACTIONS` is
+ * also the list a caller's permissions report and the role capabilities
+ * name per type (`RoleActions`), and clients validate that list, so an
+ * action added there is a change on the wire.
+ *
+ * A project's `call` and `execute` are what running an agent, a flow or
+ * an eval suite asks of the project the run is in, when the item is
+ * served by more than one project: `call` (an editor or a caller of the
+ * project) for an agent, `execute` (an editor or an executor) for a flow
+ * or a suite. They're the rights an item inherits from its project as
+ * `execute`, asked of the project itself.
+ */
+export const CHECK_ONLY_ACTIONS: Partial<Record<ObjectType, readonly Action[]>> = {
+  project: ['call', 'execute'],
+};
+
+// Tenant-global identities and structural boundaries: object types that are
+// NOT granted through project roles. A service account is one of these — its
+// `act_as` is a tenant-admin delegation, not a project capability.
+export const TENANT_GLOBAL_TYPES = ['tenant', 'org', 'team', 'user', 'service_account'] as const;
+
+// The object types reported per-type in role capabilities (the API's
+// `RoleActionsSchema` / `normalizeCapabilities`). ONE source of truth within
+// this SDK: every consumer here imports this list, so the capabilities wire
+// shape stays consistent. The runtime's `my-access` projection keeps its own
+// positively-written list for now and so CAN differ; the runtime change that
+// adds `service_account` switches that projection to import this list, after
+// which the two can't drift. Tenant-global types (`TENANT_GLOBAL_TYPES`) are
+// left out; new project-scoped content types are included automatically.
+export const PROJECT_SCOPED_TYPES: readonly ObjectType[] = OBJECT_TYPES.filter(
+  (t) => !(TENANT_GLOBAL_TYPES as readonly string[]).includes(t),
+);
+
 export interface ResourceRef {
   readonly type: ObjectType;
   readonly id: string;