@kindgi/authz 0.0.0-bootstrap.0 → 0.1.0

package/dist/types.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+// FGA authorization primitives — public shape.
+//
+// Owns:
+//   - Object type enum (must match the `type X` declarations of the
+//     authorization model the deployment's FGA store runs)
+//   - 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)
+//
+// Consumers:
+//   - Principal construction (`principal.ts`) builds {actor, onBehalfOf?}
+//   - PEPs check `ACTION_TO_RELATION[action]` on a resource through an
+//     `AuthzCheckBinding` (`check.ts`)
+//   - Policy executors reuse ObjectType for policy matching
+export const OBJECT_TYPES = [
+    // Structural / boundary
+    'tenant',
+    'org',
+    'team',
+    'project',
+    'user',
+    // Content (project-scoped, user-authored)
+    'agent',
+    'flow',
+    'tool',
+    'guardrail',
+    'eval_suite',
+    'trigger',
+    'conversation',
+    // Config (polymorphic scope)
+    'secret',
+    'env',
+    'mcp_endpoint',
+    // Runtime
+    'run',
+];
+export const ACTIONS = [
+    'read',
+    'write',
+    'delete',
+    'admin',
+    'execute',
+    'invoke',
+    'publish',
+    'rotate',
+    'fire',
+    'cancel',
+];
+export const ACTION_TO_RELATION = {
+    read: 'can_read',
+    write: 'can_write',
+    delete: 'can_delete',
+    admin: 'can_admin',
+    execute: 'can_execute',
+    invoke: 'can_invoke',
+    publish: 'can_publish',
+    rotate: 'can_rotate',
+    fire: 'can_fire',
+    cancel: 'can_cancel',
+};
+// Which verbs are meaningful for which object types. A PEP uses this to
+// reject e.g. `rotate` on `agent:X` before calling FGA.
+export const OBJECT_ACTIONS = {
+    tenant: ['read', 'admin'],
+    org: ['read', 'admin'],
+    team: ['read', 'admin'],
+    project: ['read', 'write', 'admin', 'delete'],
+    user: [],
+    agent: ['read', 'write', 'delete', 'admin', 'execute', 'publish'],
+    flow: ['read', 'write', 'delete', 'admin', 'execute', 'publish'],
+    tool: ['read', 'write', 'delete', 'admin', 'invoke'],
+    guardrail: ['read', 'write', 'delete', 'admin'],
+    eval_suite: ['read', 'write', 'delete', 'admin', 'execute', 'publish'],
+    trigger: ['read', 'write', 'delete', 'admin', 'fire'],
+    conversation: ['read', 'write', 'delete', 'admin'],
+    secret: ['read', 'write', 'delete', 'admin', 'rotate'],
+    env: ['read', 'write', 'delete', 'admin'],
+    mcp_endpoint: ['read', 'write', 'delete', 'admin'],
+    run: ['read', 'cancel', 'delete'],
+};
+export function resourceKey(ref) {
+    return `${ref.type}:${ref.id}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +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"}

package/package.json

@@ -1,7 +1,50 @@
 {
   "name": "@kindgi/authz",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.0",
+  "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": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/authz"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/authz#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kindgi/types": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --typecheck --typecheck.only --passWithNoTests",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/check.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+//
+// PDP Decision shape + pure `ref` constructor + AuthzCheckBinding
+// interface.
+//
+// This package declares the contract only. An `AuthzCheckBinding`
+// implementation resolves the tenant's FGA store and runs the relation
+// checks; deployments supply one to the enforcement sites.
+//
+
+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 function ref<T extends ObjectType>(type: T, id: string): ResourceRef {
+  return { type, id };
+}
+
+/**
+ * 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[]>;
+}

package/src/enqueue.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+//
+// Tuple-intent shape + enqueue hook contract — the interface between
+// binding write methods and a tuple outbox.
+//
+// Bindings emit `TupleIntent[]` inside their write transactions; the
+// binding implementation persists them atomically alongside the entity
+// mutation, and a worker applies them to the FGA store. The intent
+// shape is an FGA subject/relation/object triple + an optional
+// idempotency key.
+//
+
+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[];

package/src/index.ts

@@ -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';

package/src/pep.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+//
+// PEP-side primitives — framework-neutral helpers callable from any
+// HTTP layer (Hono, Express, Fastify, gRPC). The Hono middleware of
+// `@kindgi/api` lives in `packages/api/src/middleware/`.
+//
+// Two exports:
+//   - `principalFromToken`   — TokenResolution → Principal, honoring
+//                              service-account vs user semantics
+//   - `denyPayload`          — canonical structured 403 body shape
+//
+
+import type { TenantId, UserId } from '@kindgi/types';
+
+import type { Action, ObjectType } from '@kindgi/authz';
+
+import { type Principal, serviceAccountPrincipal, userPrincipal } 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 function principalFromToken(token: TokenLike): Principal {
+  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',
+  );
+}
+
+/**
+ * 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 function denyPayload(
+  action: Action,
+  resourceType: ObjectType,
+  resourceId: string,
+  reason: string,
+): DenyPayload {
+  return {
+    code: 'permission-denied',
+    action,
+    resource: `${resourceType}:${resourceId}`,
+    reason,
+  };
+}

package/src/principal.ts

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+//
+// Principal — the composite identity passed to every authz check.
+//
+// Composed of:
+//   actor:       the direct caller (who is REALLY doing this)
+//   onBehalfOf:  optional delegator (the user this action serves)
+//   scope:       optional downscoping (OAuth-style permission narrowing)
+//
+// Delegation semantics (as in cloud service-account impersonation and
+// OAuth 2.0 token exchange, RFC 8693): the effective permission is the
+// INTERSECTION of actor + onBehalfOf + scope. `AuthzCheckBinding.check`
+// (`check.ts`) enforces this: it applies the scope filter locally, then
+// checks the actor and (if set) `onBehalfOf` against FGA, and returns
+// `allowed` only when every link permits the action.
+//
+// Actor kinds:
+//   - `user`            — a human user session
+//   - `agent`           — a machine agent acting during a run.
+//                         First-class FGA subject; agents get least-
+//                         privilege grants (`machineAccessTuple` in
+//                         `tuples.ts`).
+//   - `service_account` — machine identity for capability-only bearer
+//                         tokens (CI/CD, integrations, deploy bots).
+//                         First-class FGA subject; grants via
+//                         `machineAccessTuple`. NOT tenant admin —
+//                         starts with zero authority.
+//   - `system`          — framework-initiated action (scheduled jobs,
+//                         migrations, cleanup). Maps to the
+//                         `user:system` subject, which the deployment's
+//                         tenant setup grants tenant admin.
+//
+// Tools are not principals — they are objects that agents invoke.
+//
+// The intersection semantic guards against the confused-deputy
+// problem: an agent must not be able to escalate a user's authority,
+// and a user must not be able to escalate the agent's.
+//
+
+import type { TenantId } from '@kindgi/types';
+
+import type { Action } from '@kindgi/authz';
+
+// ============================================================
+// TYPES
+// ============================================================
+
+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;
+}
+
+// ============================================================
+// CONSTRUCTORS — thin factories for readable call sites
+// ============================================================
+
+export function userPrincipal(userId: string, tenantId: TenantId): Principal {
+  return { actor: { kind: 'user', id: userId, tenantId } };
+}
+
+export function systemPrincipal(tenantId: TenantId): Principal {
+  return { actor: { kind: 'system', id: 'system', tenantId } };
+}
+
+/**
+ * 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 function serviceAccountPrincipal(serviceAccountId: string, tenantId: TenantId): Principal {
+  return { actor: { kind: 'service_account', id: serviceAccountId, tenantId } };
+}
+
+/**
+ * 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 function delegate(
+  actor: PrincipalRef,
+  onBehalfOf: PrincipalRef,
+  scope?: DownscopedPermissions,
+): Principal {
+  if (actor.tenantId !== onBehalfOf.tenantId) {
+    throw new Error(
+      `delegate: cross-tenant delegation not supported (actor.tenantId=${actor.tenantId}, onBehalfOf.tenantId=${onBehalfOf.tenantId})`,
+    );
+  }
+  return {
+    actor,
+    onBehalfOf,
+    ...(scope !== undefined ? { scope } : {}),
+  };
+}
+
+/**
+ * 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 function downscope(principal: Principal, scope: DownscopedPermissions): Principal {
+  return { ...principal, scope };
+}
+
+// ============================================================
+// FGA MAPPING — encapsulated in one place
+// ============================================================
+
+/**
+ * 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 function fgaSubject(ref: PrincipalRef): string {
+  switch (ref.kind) {
+    case 'user':
+      return `user:${ref.id}`;
+    case 'agent':
+      return `agent:${ref.id}`;
+    case 'service_account':
+      return `service_account:${ref.id}`;
+    case 'system':
+      return 'user:system';
+  }
+}

package/src/reviewer.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+//
+// Reviewer role vocabulary — the seniority ranks used by HITL approval
+// flows to gate action review. Higher rank subsumes lower: a `senior`
+// reviewer can act on anything requiring `standard`, and `admin` on
+// anything requiring `standard` or `senior`.
+//
+// Role type + rank map live in the public authz vocabulary because
+// reviewer roles are consumed by:
+//   - HITL approval bindings
+//   - API route validators and `ReviewerBinding` (@kindgi/api)
+//   - Client response types (@kindgi/client)
+//
+// Concrete role assignment / storage is caller-plugged via the
+// `ReviewerBinding` interface (declared in @kindgi/api).
+//
+
+export type ReviewerRole = 'standard' | 'senior' | 'admin';
+
+/**
+ * Rank order — index into an ordered scale so callers can express
+ * "requires >= senior" without hard-coding string comparisons.
+ * Higher number = more senior.
+ */
+export const REVIEWER_ROLE_RANK: Readonly<Record<ReviewerRole, number>> = {
+  standard: 0,
+  senior: 1,
+  admin: 2,
+};