@kindgi/authz 0.1.4-rc.0 → 0.1.4-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/dist/pep.d.ts +6 -5
  2. package/dist/pep.d.ts.map +1 -1
  3. package/dist/pep.js.map +1 -1
  4. package/dist/types.d.ts +1 -1
  5. package/dist/types.d.ts.map +1 -1
  6. package/dist/types.js +3 -1
  7. package/dist/types.js.map +1 -1
  8. package/package.json +2 -2
  9. package/src/pep.ts +7 -6
  10. package/src/types.ts +3 -1
package/dist/pep.d.ts CHANGED
@@ -30,11 +30,12 @@ export interface TokenLike {
30
30
  */
31
31
  export declare function principalFromToken(token: TokenLike): Principal;
32
32
  /**
33
- * Canonical 403 body shape. Structured so clients can distinguish
34
- * "you didn't have permission" from "your input was invalid" —
35
- * different remediation flows. Avoids leaking full evidence (that
36
- * belongs in the audit trail); reason is a human-readable summary
37
- * safe to return.
33
+ * What a denial names: the action, the resource and a reason. The API
34
+ * answers a denial as a 403 in its error envelope, `{ error: { code:
35
+ * 'permission-denied', message, details: { action, resource, reason },
36
+ * requestId } }`, so clients can tell "you didn't have permission" from
37
+ * "your input was invalid". Avoids leaking full evidence (that belongs in
38
+ * the audit trail); `reason` is a human-readable summary safe to return.
38
39
  */
39
40
  export interface DenyPayload {
40
41
  readonly code: 'permission-denied';
package/dist/pep.d.ts.map CHANGED
@@ -1 +1 @@
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"}
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;;;;;;;GAOG;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.map CHANGED
@@ -1 +1 @@
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"}
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;AAiBD,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/types.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  export declare const OBJECT_TYPES: readonly ["tenant", "org", "team", "project", "user", "agent", "flow", "tool", "guardrail", "eval_suite", "trigger", "conversation", "secret", "env", "mcp_endpoint", "run"];
2
2
  export type ObjectType = (typeof OBJECT_TYPES)[number];
3
- export declare const ACTIONS: readonly ["read", "write", "delete", "admin", "execute", "invoke", "publish", "rotate", "fire", "cancel"];
3
+ export declare const ACTIONS: readonly ["read", "write", "delete", "admin", "execute", "invoke", "publish", "rotate", "fire", "cancel", "promote"];
4
4
  export type Action = (typeof ACTIONS)[number];
5
5
  export declare const ACTION_TO_RELATION: Record<Action, string>;
6
6
  export declare const OBJECT_ACTIONS: Record<ObjectType, readonly Action[]>;
package/dist/types.d.ts.map CHANGED
@@ -1 +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,2GAWV,CAAC;AAEX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAWrD,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"}
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"}
package/dist/types.js CHANGED
@@ -47,6 +47,7 @@ export const ACTIONS = [
47
47
  'rotate',
48
48
  'fire',
49
49
  'cancel',
50
+ 'promote',
50
51
  ];
51
52
  export const ACTION_TO_RELATION = {
52
53
  read: 'can_read',
@@ -59,6 +60,7 @@ export const ACTION_TO_RELATION = {
59
60
  rotate: 'can_rotate',
60
61
  fire: 'can_fire',
61
62
  cancel: 'can_cancel',
63
+ promote: 'can_promote',
62
64
  };
63
65
  // Which verbs are meaningful for which object types. A PEP uses this to
64
66
  // reject e.g. `rotate` on `agent:X` before calling FGA.
@@ -68,7 +70,7 @@ export const OBJECT_ACTIONS = {
68
70
  team: ['read', 'admin'],
69
71
  project: ['read', 'write', 'admin', 'delete'],
70
72
  user: [],
71
- agent: ['read', 'write', 'delete', 'admin', 'execute', 'publish'],
73
+ agent: ['read', 'write', 'delete', 'admin', 'execute', 'publish', 'promote'],
72
74
  flow: ['read', 'write', 'delete', 'admin', 'execute', 'publish'],
73
75
  tool: ['read', 'write', 'delete', 'admin', 'invoke'],
74
76
  guardrail: ['read', 'write', 'delete', 'admin'],
package/dist/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,+CAA+C;AAC/C,EAAE;AACF,QAAQ;AACR,oEAAoE;AACpE,2DAA2D;AAC3D,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,EAAE;AACF,aAAa;AACb,0EAA0E;AAC1E,uEAAuE;AACvE,uCAAuC;AACvC,4DAA4D;AAE5D,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,wBAAwB;IACxB,QAAQ;IACR,KAAK;IACL,MAAM;IACN,SAAS;IACT,MAAM;IACN,0CAA0C;IAC1C,OAAO;IACP,MAAM;IACN,MAAM;IACN,WAAW;IACX,YAAY;IACZ,SAAS;IACT,cAAc;IACd,6BAA6B;IAC7B,QAAQ;IACR,KAAK;IACL,cAAc;IACd,UAAU;IACV,KAAK;CACG,CAAC;AAIX,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,MAAM;IACN,OAAO;IACP,QAAQ;IACR,OAAO;IACP,SAAS;IACT,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,MAAM;IACN,QAAQ;CACA,CAAC;AAIX,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,WAAW;IAClB,MAAM,EAAE,YAAY;IACpB,KAAK,EAAE,WAAW;IAClB,OAAO,EAAE,aAAa;IACtB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,aAAa;IACtB,MAAM,EAAE,YAAY;IACpB,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,YAAY;CACrB,CAAC;AAEF,wEAAwE;AACxE,wDAAwD;AACxD,MAAM,CAAC,MAAM,cAAc,GAA0C;IACnE,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,GAAG,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC;IAC7C,IAAI,EAAE,EAAE;IAER,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC;IACjE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC;IAChE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IACpD,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;IAC/C,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC;IACtE,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC;IACrD,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;IAElD,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IACtD,GAAG,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;IACzC,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;IAElD,GAAG,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC;CAClC,CAAC;AAOF,MAAM,UAAU,WAAW,CAAC,GAAgB;IAC1C,OAAO,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;AACjC,CAAC"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,+CAA+C;AAC/C,EAAE;AACF,QAAQ;AACR,oEAAoE;AACpE,2DAA2D;AAC3D,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,EAAE;AACF,aAAa;AACb,0EAA0E;AAC1E,uEAAuE;AACvE,uCAAuC;AACvC,4DAA4D;AAE5D,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,wBAAwB;IACxB,QAAQ;IACR,KAAK;IACL,MAAM;IACN,SAAS;IACT,MAAM;IACN,0CAA0C;IAC1C,OAAO;IACP,MAAM;IACN,MAAM;IACN,WAAW;IACX,YAAY;IACZ,SAAS;IACT,cAAc;IACd,6BAA6B;IAC7B,QAAQ;IACR,KAAK;IACL,cAAc;IACd,UAAU;IACV,KAAK;CACG,CAAC;AAIX,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,MAAM;IACN,OAAO;IACP,QAAQ;IACR,OAAO;IACP,SAAS;IACT,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,SAAS;CACD,CAAC;AAIX,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,WAAW;IAClB,MAAM,EAAE,YAAY;IACpB,KAAK,EAAE,WAAW;IAClB,OAAO,EAAE,aAAa;IACtB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,aAAa;IACtB,MAAM,EAAE,YAAY;IACpB,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,aAAa;CACvB,CAAC;AAEF,wEAAwE;AACxE,wDAAwD;AACxD,MAAM,CAAC,MAAM,cAAc,GAA0C;IACnE,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,GAAG,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC;IAC7C,IAAI,EAAE,EAAE;IAER,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC;IAC5E,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC;IAChE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IACpD,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;IAC/C,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC;IACtE,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC;IACrD,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;IAElD,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IACtD,GAAG,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;IACzC,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;IAElD,GAAG,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC;CAClC,CAAC;AAOF,MAAM,UAAU,WAAW,CAAC,GAAgB;IAC1C,OAAO,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;AACjC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kindgi/authz",
3
- "version": "0.1.4-rc.0",
3
+ "version": "0.1.4-rc.2",
4
4
  "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.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -28,7 +28,7 @@
28
28
  "README.md"
29
29
  ],
30
30
  "dependencies": {
31
- "@kindgi/types": "0.1.4-rc.0"
31
+ "@kindgi/types": "0.1.4-rc.2"
32
32
  },
33
33
  "engines": {
34
34
  "node": ">=22.12.0"
package/src/pep.ts CHANGED
@@ -9,7 +9,7 @@
9
9
  // Two exports:
10
10
  // - `principalFromToken` — TokenResolution → Principal, honoring
11
11
  // service-account vs user semantics
12
- // - `denyPayload` — canonical structured 403 body shape
12
+ // - `denyPayload` — what a 403 denial names (its envelope's `details`)
13
13
  //
14
14
 
15
15
  import type { TenantId, UserId } from '@kindgi/types';
@@ -59,11 +59,12 @@ export function principalFromToken(token: TokenLike): Principal {
59
59
  }
60
60
 
61
61
  /**
62
- * Canonical 403 body shape. Structured so clients can distinguish
63
- * "you didn't have permission" from "your input was invalid" —
64
- * different remediation flows. Avoids leaking full evidence (that
65
- * belongs in the audit trail); reason is a human-readable summary
66
- * safe to return.
62
+ * What a denial names: the action, the resource and a reason. The API
63
+ * answers a denial as a 403 in its error envelope, `{ error: { code:
64
+ * 'permission-denied', message, details: { action, resource, reason },
65
+ * requestId } }`, so clients can tell "you didn't have permission" from
66
+ * "your input was invalid". Avoids leaking full evidence (that belongs in
67
+ * the audit trail); `reason` is a human-readable summary safe to return.
67
68
  */
68
69
  export interface DenyPayload {
69
70
  readonly code: 'permission-denied';
package/src/types.ts CHANGED
@@ -52,6 +52,7 @@ export const ACTIONS = [
52
52
  'rotate',
53
53
  'fire',
54
54
  'cancel',
55
+ 'promote',
55
56
  ] as const;
56
57
 
57
58
  export type Action = (typeof ACTIONS)[number];
@@ -67,6 +68,7 @@ export const ACTION_TO_RELATION: Record<Action, string> = {
67
68
  rotate: 'can_rotate',
68
69
  fire: 'can_fire',
69
70
  cancel: 'can_cancel',
71
+ promote: 'can_promote',
70
72
  };
71
73
 
72
74
  // Which verbs are meaningful for which object types. A PEP uses this to
@@ -78,7 +80,7 @@ export const OBJECT_ACTIONS: Record<ObjectType, readonly Action[]> = {
78
80
  project: ['read', 'write', 'admin', 'delete'],
79
81
  user: [],
80
82
 
81
- agent: ['read', 'write', 'delete', 'admin', 'execute', 'publish'],
83
+ agent: ['read', 'write', 'delete', 'admin', 'execute', 'publish', 'promote'],
82
84
  flow: ['read', 'write', 'delete', 'admin', 'execute', 'publish'],
83
85
  tool: ['read', 'write', 'delete', 'admin', 'invoke'],
84
86
  guardrail: ['read', 'write', 'delete', 'admin'],