@zhama/tego-plugin-sdk 0.0.0-stage → 1.36.0

package/dist/access.d.cts

@@ -0,0 +1,884 @@
+import { D as DelegationAction, G as Grants, A as AccessCatalog, a as GrantValue, T as TypedAccessCatalog, P as PermissionOf } from './catalog-CSSbrfEf.cjs';
+export { b as AccessCatalogError, c as AccessCatalogInput, d as AgentPolicy, B as BUILTIN_PRINCIPAL_KINDS, C as CatalogIssue, e as CatalogPermission, f as CatalogRole, g as DELEGATION_ACTIONS, h as GLOBAL_DOMAIN, H as HOST_ADMIN_ROLE, R as RESERVED_GROUP, i as RESERVED_PERMISSIONS, j as accessCatalogFromJson, k as accessCatalogSchema, l as defineAccess, m as grantProblem, v as validateAccessCatalog } from './catalog-CSSbrfEf.cjs';
+import { PluginUserContext } from './frontend.cjs';
+import { PluginHostApi } from './server.cjs';
+import { z } from 'zod';
+export { expandImplications, mergeGrant, scopeRank } from './access-implications.cjs';
+
+/**
+ * The pure core of the decision engine: given who the caller is and what the
+ * store holds, which permissions do they have, and why.
+ *
+ * No I/O here. The store loads rows, the principal sources say which units or
+ * groups the caller belongs to, and this module only combines them. That is
+ * what lets the contract fixtures — shared with the Python SDK — and the
+ * property tests exercise the real semantics without a database.
+ */
+
+interface AccessSubject {
+    tenantId: string;
+    userId: string;
+    /** The host's role names for the person, as the gateway signed them. */
+    hostRoles: readonly string[];
+    /** Set when a digital employee acts for `userId`. */
+    agent?: {
+        avatarId: string;
+        delegation: readonly DelegationAction[];
+    };
+}
+declare function subjectFromContext(ctx: PluginUserContext): AccessSubject;
+interface AccessDomain {
+    type: string;
+    id: string;
+}
+interface AccessRole {
+    id: string;
+    /** The catalog key of a built-in role; null for a custom one. */
+    key: string | null;
+    builtin: boolean;
+    /** A custom role usable only inside this domain; null for a global role. */
+    domain: AccessDomain | null;
+    name: string;
+    description: string;
+    grants: Grants;
+    catalogVersion: number;
+    createdAt: string;
+    updatedAt: string;
+    updatedBy: string | null;
+}
+interface AssignmentPrincipal {
+    kind: string;
+    id: string;
+    /** For a unit or a group: also everyone in the units below it. */
+    includeDescendants: boolean;
+    /** For a unit: only members holding one of these unit roles. Null for all. */
+    unitRoles: string[] | null;
+}
+interface AccessAssignment {
+    id: string;
+    roleId: string;
+    principal: AssignmentPrincipal;
+    domain: AccessDomain | null;
+    createdBy: string;
+    createdAt: string;
+}
+/** A unit or group the subject belongs to. */
+interface PrincipalMembership {
+    kind: string;
+    id: string;
+    /** Enclosing units, for assignments made with `includeDescendants`. */
+    ancestors: readonly string[];
+    /** The subject's role inside it, matched against `unitRoles`. */
+    role?: string;
+}
+type GrantSourceKind = 'assignment' | 'hostRole' | 'unassigned';
+interface GrantSource {
+    roleId: string;
+    roleKey: string | null;
+    source: GrantSourceKind;
+    /** The assignment's principal, or the host role name. */
+    principal?: {
+        kind: string;
+        id: string;
+    };
+    hostRole?: string;
+    domain?: AccessDomain | null;
+    /** An assignment made at an ancestor of the resolved domain. */
+    inherited?: true;
+}
+type DecisionReason = 'granted' | 'not_granted' | 'scope_mismatch' | 'agent_forbidden' | 'delegation_missing';
+interface Decision {
+    allowed: boolean;
+    permission: string;
+    /** The scope held, for a scoped permission that is granted. */
+    scope: string | null;
+    /** The scope that matched the resource, when a resource was checked. */
+    matchedScope?: string;
+    reason: DecisionReason;
+    via: GrantSource[];
+}
+interface ResolveInput {
+    catalog: AccessCatalog;
+    subject: AccessSubject;
+    /** Every role of the tenant, by id. */
+    roles: ReadonlyMap<string, AccessRole>;
+    /** Assignments naming the subject or any of its memberships, in any domain. */
+    assignments: readonly AccessAssignment[];
+    memberships: readonly PrincipalMembership[];
+    unassignedRoleId: string | null;
+    domain: AccessDomain | null;
+    /** For a domain of a hierarchical type: see `DomainInheritance`. */
+    inheritance?: DomainInheritance;
+}
+/**
+ * How assignments made above a domain reach into it.
+ *
+ * `ancestors` are the resolved domain's, nearest first. An assignment at any of
+ * them applies here with the role's grants passed through `inherit`, which can
+ * only narrow: a grant it adds, or widens past the role's own, is ignored.
+ */
+interface DomainInheritance {
+    ancestors: readonly AccessDomain[];
+    inherit(grants: Grants): Grants;
+}
+interface HeldGrant {
+    value: GrantValue;
+    via: GrantSource[];
+}
+/**
+ * What one subject holds in one domain.
+ *
+ * Grants are allow-only and combine monotonically: a union across roles, the
+ * widest scope wins, implications are expanded per role. A digital employee
+ * then keeps only what each permission's agent policy and the live delegation
+ * allow — never more than the person it acts for.
+ */
+declare class EffectiveGrants {
+    readonly catalog: AccessCatalog;
+    readonly subject: AccessSubject;
+    readonly domain: AccessDomain | null;
+    private readonly held;
+    private readonly withheld;
+    /** Every role that contributed, with how. */
+    readonly sources: readonly GrantSource[];
+    /** Ids of the domains in which the subject has explicit assignments. */
+    readonly assignedDomains: readonly AccessDomain[];
+    constructor(catalog: AccessCatalog, subject: AccessSubject, domain: AccessDomain | null, held: ReadonlyMap<string, HeldGrant>, withheld: ReadonlyMap<string, {
+        reason: 'agent_forbidden' | 'delegation_missing';
+        via: GrantSource[];
+    }>, 
+    /** Every role that contributed, with how. */
+    sources: readonly GrantSource[], 
+    /** Ids of the domains in which the subject has explicit assignments. */
+    assignedDomains: readonly AccessDomain[]);
+    /** The grant value, or undefined when the permission is not held. */
+    value(permission: string): GrantValue | undefined;
+    can(permission: string): boolean;
+    /** The scope held, or null for an unscoped permission or one not held. */
+    scope(permission: string): string | null;
+    /** Whether the permission is held at `scope` or wider. */
+    atLeast(permission: string, scope: string): boolean;
+    via(permission: string): GrantSource[];
+    /** Why a permission is not held: not granted, or withheld from the agent. */
+    denial(permission: string): DecisionReason | null;
+    permissions(): Record<string, GrantValue>;
+    /** Whether `access.manage` comes from a host role binding. */
+    managesThroughHostRole(): boolean;
+    /** The decision for a functional check, before any resource is looked at. */
+    decide(permission: string): Decision;
+}
+/**
+ * The decision for `permission` on `resource`.
+ *
+ * Without a resource, or for an unscoped permission, this is the functional
+ * check. Otherwise the resource must match the held scope or one narrower on
+ * the ladder, tried widest first so `all` short-circuits.
+ */
+declare function decideResource(grants: EffectiveGrants, permission: string, resource: unknown, matches: (scope: string) => boolean | Promise<boolean>): Promise<Decision>;
+/** Whether an assignment applies when resolving in `domain`. */
+declare function assignmentInDomain(assignment: AccessAssignment, domain: AccessDomain | null): boolean;
+/** Whether an assignment names the subject, directly or through a membership. */
+declare function assignmentMatches(assignment: AccessAssignment, subject: AccessSubject, memberships: readonly PrincipalMembership[]): boolean;
+/**
+ * Drops grants the current catalog does not recognise.
+ *
+ * A custom role saved under an older catalog may name a permission since
+ * removed, or a scope since dropped from its ladder. Ignoring the grant —
+ * rather than failing the request or widening it — is the only reading that
+ * cannot hand anyone more than the catalog now describes.
+ */
+declare function validGrants(catalog: AccessCatalog, grants: Grants): Grants;
+declare function resolveGrants(input: ResolveInput): EffectiveGrants;
+
+/**
+ * SQL fragments a scope contributes to a list query.
+ *
+ * Built with a tagged template so values can only ever be parameters: there
+ * is no way to splice one into the text. Identifiers (the caller's table
+ * alias and column names) go through {@link ident}, which accepts only plain
+ * lower-case names — they are the one thing a parameter cannot carry.
+ *
+ * Placeholders are numbered when the fragment is rendered, against the
+ * caller's own parameter list, so a fragment composes into any query without
+ * either side knowing the other's numbering.
+ */
+declare const IDENT: unique symbol;
+declare const FRAGMENT: unique symbol;
+interface Identifier {
+    readonly [IDENT]: string;
+}
+/**
+ * Only {@link sql} makes one: an interpolated object that merely has
+ * `strings` and `values` is a parameter, so its text never reaches the query.
+ */
+interface SqlFragment {
+    readonly [FRAGMENT]: true;
+    readonly strings: readonly string[];
+    readonly values: readonly unknown[];
+}
+/** A lower-case SQL identifier; anything else throws. */
+declare function ident(name: string): Identifier;
+/**
+ * Tagged template producing a fragment.
+ *
+ * Interpolated values become parameters, an {@link ident} becomes the
+ * identifier, and a nested fragment is inlined with its own parameters.
+ */
+declare function sql(strings: TemplateStringsArray, ...values: unknown[]): SqlFragment;
+declare const TRUE_FRAGMENT: SqlFragment;
+declare const FALSE_FRAGMENT: SqlFragment;
+/** `(a) OR (b) …`, collapsing to TRUE/FALSE where that is already decided. */
+declare function orFragments(fragments: readonly SqlFragment[]): SqlFragment;
+/**
+ * Renders a fragment with `$n` placeholders starting after `offset`.
+ *
+ * `offset` is the number of parameters the surrounding query already uses;
+ * append the returned `params` to them.
+ */
+declare function renderFragment(fragment: SqlFragment, offset?: number): {
+    text: string;
+    params: unknown[];
+};
+/**
+ * Splices a fragment into a query that already has `params`.
+ *
+ * Returns the fragment's text, numbered after the existing parameters, and
+ * the combined parameter list.
+ */
+declare function bindFragment(params: readonly unknown[], fragment: SqlFragment): {
+    text: string;
+    params: unknown[];
+};
+
+/**
+ * Scope evaluators: what a scope name means for one resource and for a list.
+ *
+ * Each evaluator answers both questions — `matches` for a single resource,
+ * `filter` for the WHERE clause of a list — so the two cannot drift apart:
+ * the classic leak where a list shows rows the detail page refuses (or the
+ * other way round) comes from writing them separately.
+ */
+
+/** Where the filtered table sits in the caller's query. */
+interface ScopeRef {
+    /** The table alias the fragment qualifies its columns with. */
+    alias: string;
+    /** Logical column name → actual column, for evaluators that need one. */
+    columns?: Record<string, string>;
+}
+interface ScopeContext {
+    host: PluginHostApi;
+    permission: string;
+}
+interface ScopeEvaluator<R = unknown> {
+    matches(subject: AccessSubject, resource: R, context: ScopeContext): boolean | Promise<boolean>;
+    filter(subject: AccessSubject, ref: ScopeRef): SqlFragment;
+}
+/** The column an evaluator needs, validated as an identifier. */
+declare function refColumn(ref: ScopeRef, name: string): ReturnType<typeof ident>;
+/** Every resource. */
+declare const allScope: ScopeEvaluator<unknown>;
+/** Resources the subject owns: `resource.ownerId`, column `ownerId`. */
+declare const ownScope: ScopeEvaluator<{
+    ownerId: string | null;
+}>;
+declare const BUILTIN_SCOPES: Record<string, ScopeEvaluator<never>>;
+
+/**
+ * A denied check, carrying the decision that denied it.
+ *
+ * 403 says "you cannot use this", which reveals nothing about any record.
+ * 404 is for a resource outside the caller's scope when the route asked to
+ * conceal it: confirming that a confidential record exists is itself a leak.
+ */
+declare class AccessDeniedError extends Error {
+    readonly decision: Decision;
+    readonly status: 403 | 404;
+    constructor(decision: Decision, status: 403 | 404);
+}
+/** A refused admin operation, with the status and a stable code. */
+declare class AccessAdminError extends Error {
+    readonly status: 400 | 403 | 404 | 409;
+    readonly code: string;
+    constructor(status: 400 | 403 | 404 | 409, code: string, message: string);
+}
+
+/**
+ * Reads and writes of the `tego_access_*` tables.
+ *
+ * Plain parameterized SQL over the plugin's scoped connection, so it runs the
+ * same in every plugin whatever query layer the plugin itself uses. Every
+ * statement filters on `tenant_id`.
+ */
+
+interface Queryable {
+    query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+}
+interface AccessSettingsRow {
+    unassignedRoleId: string | null;
+    version: number;
+    epoch: string;
+    updatedAt: string;
+    updatedBy: string | null;
+}
+interface AuditEntry {
+    id: string;
+    actorId: string | null;
+    action: string;
+    targetType: string;
+    targetId: string;
+    before: unknown;
+    after: unknown;
+    at: string;
+}
+
+/**
+ * The decision point: `createAccess` binds a catalog to its scope evaluators
+ * and principal sources, and hands out a session per caller.
+ *
+ * A session is cheap and lives for one request (or one storage check). It
+ * reads the tenant's access version once, and everything derived from that —
+ * role definitions, the caller's assignments — is cached across requests
+ * under that version, so a change made in any process is seen by every other
+ * process on its next request without any invalidation message.
+ */
+
+interface PrincipalEntry {
+    id: string;
+    displayName: string;
+    parentId?: string | null;
+    active?: boolean;
+}
+interface PrincipalQuery {
+    search?: string;
+    ids?: string[];
+    offset: number;
+    limit: number;
+}
+/** A kind of principal roles can be assigned to, beyond a single user. */
+interface PrincipalSource {
+    kind: string;
+    /** The subject's memberships of this kind. */
+    memberships(subject: AccessSubject, host: PluginHostApi): Promise<PrincipalMembership[]>;
+    /** Lookup and search, for the admin screens and for validating a grantee. */
+    list(host: PluginHostApi, query: PrincipalQuery): Promise<{
+        items: PrincipalEntry[];
+        hasMore: boolean;
+    }>;
+}
+/** The plugin's own records a domain type names (EHS's organizations). */
+interface DomainSource {
+    /** Display names by id; an id missing from the result does not exist. */
+    describe(ids: string[], host: PluginHostApi): Promise<Map<string, string>>;
+    /**
+     * Required for a hierarchical domain type: the ancestors of `id`, nearest
+     * first. Leave out one that should confer nothing below it (a deactivated
+     * organization, say); the walk continues past it.
+     */
+    ancestors?(id: string, host: PluginHostApi): Promise<string[]>;
+    /**
+     * Required for a hierarchical domain type: what a role assigned at an
+     * ancestor confers here, given the role's grants with implications
+     * expanded. It can only narrow; see `DomainInheritance`.
+     */
+    inherit?(grants: Grants): Grants;
+}
+type AccessChange = {
+    type: 'role.created';
+    role: AccessRole;
+} | {
+    type: 'role.updated';
+    role: AccessRole;
+    before: AccessRole;
+}
+/**
+ * Also when `reconcile` retires a built-in role the catalog dropped; its
+ * assignments go with it and are not reported one by one.
+ */
+ | {
+    type: 'role.deleted';
+    role: AccessRole;
+} | {
+    type: 'assignment.created';
+    assignment: AccessAssignment;
+} | {
+    type: 'assignment.deleted';
+    assignment: AccessAssignment;
+} | {
+    type: 'settings.updated';
+    before: {
+        unassignedRoleId: string | null;
+    };
+    after: {
+        unassignedRoleId: string | null;
+    };
+} | {
+    type: 'catalog.reconciled';
+    report: ReconcileReport;
+};
+interface AccessHooks {
+    /**
+     * Runs inside the transaction that made the change, after it.
+     *
+     * For data derived from roles — compiled sharing rules, an index marked
+     * stale — that has to commit or roll back together with the change.
+     * Throwing rolls the change back.
+     */
+    onChange?(tx: Queryable, change: AccessChange, context: {
+        tenantId: string;
+        host: PluginHostApi;
+    }): Promise<void>;
+}
+interface CreateAccessOptions<C extends AccessCatalog> {
+    catalog: C;
+    /** Evaluators for the catalog's scopes; `all` and `own` are built in. */
+    evaluators?: Record<string, ScopeEvaluator<never>>;
+    /** Principal kinds beyond `user` and `unit`. */
+    principals?: PrincipalSource[];
+    /** One source per domain type the catalog declares. */
+    domains?: Record<string, DomainSource>;
+    hooks?: AccessHooks;
+    /** Cached assignment sets across requests. Defaults to 2000. */
+    cacheSize?: number;
+}
+interface ReconcileReport {
+    created: string[];
+    updated: string[];
+    retired: string[];
+    /** Custom-role grants the catalog no longer recognises, ignored until saved. */
+    staleGrants: {
+        roleId: string;
+        permission: string;
+    }[];
+}
+interface AccessSnapshot {
+    userId: string;
+    agent: boolean;
+    catalogVersion: number;
+    domain: AccessDomain | null;
+    permissions: Record<string, GrantValue>;
+    /** Navigation key → visible. Keys the catalog does not gate are absent. */
+    menus: Record<string, boolean>;
+    roles: {
+        id: string;
+        key: string | null;
+        builtin: boolean;
+        name: string;
+        nameKey: string | null;
+        source: GrantSourceKind;
+        hostRole?: string;
+    }[];
+    /** Domain ids by type in which the caller has explicit assignments. */
+    domains: Record<string, string[]>;
+}
+interface TenantState {
+    settings: AccessSettingsRow;
+    roles: Map<string, AccessRole>;
+    kinds: string[];
+}
+/** Users are matched by id; this source exists for lookup. */
+declare const userPrincipalSource: PrincipalSource;
+/** The host's organization units, with the member's role in each. */
+declare const unitPrincipalSource: PrincipalSource;
+declare function domainKey(domain: AccessDomain | null | undefined): string;
+interface CheckOptions {
+    domain?: AccessDomain | null;
+}
+declare class AccessEngine<P extends string = string> {
+    readonly catalog: AccessCatalog;
+    readonly evaluators: ReadonlyMap<string, ScopeEvaluator<never>>;
+    readonly principalSources: ReadonlyMap<string, PrincipalSource>;
+    readonly domainSources: ReadonlyMap<string, DomainSource>;
+    readonly hooks: AccessHooks;
+    private readonly tenantCache;
+    private readonly assignmentCache;
+    constructor(options: CreateAccessOptions<AccessCatalog>);
+    forRequest(ctx: PluginUserContext, host: PluginHostApi): AccessSession<P>;
+    forSubject(subject: AccessSubject, host: PluginHostApi): AccessSession<P>;
+    /**
+     * A person as the directory knows them now, or null when inactive.
+     *
+     * For the entry points that carry a user id but no signed context: the
+     * storage authorizer, and explaining someone else's access.
+     */
+    subjectFor(userId: string, host: PluginHostApi): Promise<AccessSubject | null>;
+    /** @internal */
+    tenantState(host: PluginHostApi): Promise<TenantState>;
+    /** @internal */
+    assignments(host: PluginHostApi, settings: AccessSettingsRow, principals: {
+        kind: string;
+        id: string;
+    }[]): Promise<AccessAssignment[]>;
+    /**
+     * Brings the built-in roles in line with the catalog.
+     *
+     * Run from the backend's `start`: built-in roles are owned by the catalog,
+     * so their grants are rewritten whenever it changes, and a built-in role it
+     * no longer lists is removed with its assignments. Serialized across
+     * processes by an advisory lock, and a no-op — no version bump — when
+     * nothing differs.
+     */
+    reconcile(host: PluginHostApi): Promise<ReconcileReport>;
+}
+declare class AccessSession<P extends string = string> {
+    readonly engine: AccessEngine<P>;
+    readonly subject: AccessSubject;
+    readonly host: PluginHostApi;
+    private state?;
+    private memberships?;
+    private readonly grantsByDomain;
+    constructor(engine: AccessEngine<P>, subject: AccessSubject, host: PluginHostApi);
+    /** @internal */
+    tenant(): Promise<TenantState>;
+    private loadMemberships;
+    private inheritance;
+    /**
+     * Everything the subject holds in `domain` (global when omitted), including
+     * what assignments at its ancestors pass down when its type is hierarchical.
+     */
+    grants(domain?: AccessDomain | null): Promise<EffectiveGrants>;
+    can(permission: P, options?: CheckOptions): Promise<boolean>;
+    /**
+     * Whether `permission` is held globally or in any domain the subject has an
+     * assignment in. Inheritance only narrows what an assignment grants, so a
+     * domain below those cannot hold more.
+     */
+    holdsAnywhere(permission: P): Promise<boolean>;
+    /** The scope held, or null when not held or the permission has no scopes. */
+    scope(permission: P, options?: CheckOptions): Promise<string | null>;
+    /**
+     * The decision for `permission`, and for `resource` when one is given.
+     *
+     * Without a resource this is the functional check: is the permission held
+     * at any scope. With one, a scoped permission must also match it under the
+     * held scope or one narrower.
+     */
+    authorize(permission: P, resource?: unknown, options?: CheckOptions): Promise<Decision>;
+    /**
+     * {@link authorize}, throwing when denied.
+     *
+     * A permission not held at all is a 403 whatever `conceal` says: that
+     * reveals only that the caller cannot use the feature. A resource outside
+     * the held scope is a 404 under `conceal`, so its existence stays hidden.
+     */
+    assert(permission: P, resource?: unknown, options?: CheckOptions & {
+        conceal?: boolean;
+    }): Promise<Decision>;
+    /**
+     * A WHERE-clause fragment selecting the rows `permission` reaches.
+     *
+     * FALSE when the permission is not held, TRUE when it is unscoped or held at
+     * a scope that covers everything, otherwise the OR of every scope up to the
+     * held one — the same reading {@link authorize} applies to one resource.
+     */
+    filter(permission: P, ref: ScopeRef, options?: CheckOptions): Promise<SqlFragment>;
+    /** What `/access/me` answers: enough for a UI to gate itself. */
+    snapshot(options?: CheckOptions): Promise<AccessSnapshot>;
+    /** Whether the caller manages access (holds `access.manage`). */
+    manages(options?: CheckOptions): Promise<boolean>;
+}
+declare function createAccess<C extends TypedAccessCatalog<string>>(options: CreateAccessOptions<C>): AccessEngine<PermissionOf<C>>;
+
+/**
+ * The access administration operations, independent of any HTTP framework.
+ *
+ * The Hono routes (and the Python SDK's FastAPI routes, which mirror this
+ * file) only parse input and map errors; every rule lives here:
+ *
+ * - every operation needs `access.manage` in the domain it touches, so an
+ *   assignment of `access.manage` inside one domain delegates exactly that
+ *   domain's administration;
+ * - no escalation: whoever writes a role, assigns it, removes an assignment
+ *   of it or makes it the default must already hold everything it grants, at
+ *   the same scope or wider. Someone managing access through a host role
+ *   binding is exempt — that is the recovery path when nobody else can;
+ * - a role marked `assignableBy: host-admin` is assigned and unassigned only
+ *   through such a host role;
+ * - the catalog's per-user role limits, and referential rules the schema
+ *   cannot express (a domain role assigned in its own domain only).
+ *
+ * Every write runs in one transaction that bumps the tenant's access version,
+ * appends to the audit log and runs the plugin's change hook.
+ */
+
+declare const domainInputSchema: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: string;
+    id: string;
+}, {
+    type: string;
+    id: string;
+}>;
+declare const createRoleInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    grants: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodLiteral<true>, z.ZodString]>>;
+    domain: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        id: string;
+    }, {
+        type: string;
+        id: string;
+    }>>>;
+}, "strict", z.ZodTypeAny, {
+    grants: Record<string, string | true>;
+    domain: {
+        type: string;
+        id: string;
+    } | null;
+    name: string;
+    description: string;
+}, {
+    grants: Record<string, string | true>;
+    name: string;
+    domain?: {
+        type: string;
+        id: string;
+    } | null | undefined;
+    description?: string | undefined;
+}>;
+declare const updateRoleInputSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    grants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodLiteral<true>, z.ZodString]>>>;
+}, "strict", z.ZodTypeAny, {
+    grants?: Record<string, string | true> | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+}, {
+    grants?: Record<string, string | true> | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+}>;
+declare const cloneRoleInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    domain: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        id: string;
+    }, {
+        type: string;
+        id: string;
+    }>>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    domain?: {
+        type: string;
+        id: string;
+    } | null | undefined;
+}, {
+    name: string;
+    domain?: {
+        type: string;
+        id: string;
+    } | null | undefined;
+}>;
+declare const createAssignmentInputSchema: z.ZodObject<{
+    roleId: z.ZodString;
+    principal: z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+        includeDescendants: z.ZodDefault<z.ZodBoolean>;
+        unitRoles: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodEnum<["owner", "admin", "member", "viewer"]>, "many">>>;
+    }, "strict", z.ZodTypeAny, {
+        kind: string;
+        id: string;
+        includeDescendants: boolean;
+        unitRoles: ("admin" | "owner" | "member" | "viewer")[] | null;
+    }, {
+        kind: string;
+        id: string;
+        includeDescendants?: boolean | undefined;
+        unitRoles?: ("admin" | "owner" | "member" | "viewer")[] | null | undefined;
+    }>;
+    domain: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        id: string;
+    }, {
+        type: string;
+        id: string;
+    }>>>;
+}, "strict", z.ZodTypeAny, {
+    domain: {
+        type: string;
+        id: string;
+    } | null;
+    principal: {
+        kind: string;
+        id: string;
+        includeDescendants: boolean;
+        unitRoles: ("admin" | "owner" | "member" | "viewer")[] | null;
+    };
+    roleId: string;
+}, {
+    principal: {
+        kind: string;
+        id: string;
+        includeDescendants?: boolean | undefined;
+        unitRoles?: ("admin" | "owner" | "member" | "viewer")[] | null | undefined;
+    };
+    roleId: string;
+    domain?: {
+        type: string;
+        id: string;
+    } | null | undefined;
+}>;
+declare const assignmentQuerySchema: z.ZodObject<{
+    roleId: z.ZodOptional<z.ZodString>;
+    principalKind: z.ZodOptional<z.ZodString>;
+    principalId: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    roleId?: string | undefined;
+    principalKind?: string | undefined;
+    principalId?: string | undefined;
+}, {
+    roleId?: string | undefined;
+    principalKind?: string | undefined;
+    principalId?: string | undefined;
+}>;
+declare const principalQuerySchema: z.ZodObject<{
+    kind: z.ZodString;
+    search: z.ZodOptional<z.ZodString>;
+    ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    offset: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    kind: string;
+    offset: number;
+    limit: number;
+    search?: string | undefined;
+    ids?: string[] | undefined;
+}, {
+    kind: string;
+    search?: string | undefined;
+    ids?: string[] | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}>;
+declare const updateSettingsInputSchema: z.ZodObject<{
+    unassignedRoleId: z.ZodNullable<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    unassignedRoleId: string | null;
+}, {
+    unassignedRoleId: string | null;
+}>;
+declare const auditQuerySchema: z.ZodObject<{
+    offset: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    offset: number;
+    limit: number;
+}, {
+    offset?: number | undefined;
+    limit?: number | undefined;
+}>;
+interface RoleView {
+    id: string;
+    key: string | null;
+    builtin: boolean;
+    domain: AccessDomain | null;
+    name: string;
+    nameKey: string | null;
+    description: string;
+    descriptionKey: string | null;
+    grants: Grants;
+    assignableBy: 'access-manager' | 'host-admin';
+    exemptFromRoleLimit: boolean;
+    assignmentCount: number;
+    isDefault: boolean;
+    /** Grants the current catalog no longer recognises; dropped on next save. */
+    staleGrants: string[];
+    updatedAt: string;
+    updatedBy: string | null;
+}
+interface AssignmentView extends AccessAssignment {
+    principalName: string | null;
+    domainName: string | null;
+}
+interface ExplainView {
+    userId: string;
+    domain: AccessDomain | null;
+    roles: (GrantSource & {
+        name: string;
+        nameKey: string | null;
+    })[];
+    permissions: Pick<Decision, 'permission' | 'allowed' | 'scope' | 'reason' | 'via'>[];
+}
+interface AuditEntryView extends AuditEntry {
+    actorName: string | null;
+}
+interface SettingsView {
+    unassignedRoleId: string | null;
+    version: number;
+    updatedAt: string;
+    updatedBy: string | null;
+}
+/** The grants of `grants` the actor does not hold at the same scope or wider. */
+declare function uncoveredGrants(catalog: AccessCatalog, actor: EffectiveGrants, grants: Grants): string[];
+declare class AccessAdmin {
+    private readonly session;
+    constructor(session: AccessSession);
+    private get engine();
+    private get catalog();
+    private get host();
+    private get tenantId();
+    private get actorId();
+    /** The caller's grants in `domain`, refusing anyone without `access.manage`. */
+    private manager;
+    private assertCovers;
+    private assertDomain;
+    private validateGrants;
+    private write;
+    private role;
+    private view;
+    catalogView(domain: AccessDomain | null): Promise<AccessCatalog>;
+    /** Global roles, plus the roles of `domain` when one is given. */
+    listRoles(domain: AccessDomain | null): Promise<RoleView[]>;
+    createRole(input: z.output<typeof createRoleInputSchema>): Promise<RoleView>;
+    private assertNameFree;
+    updateRole(id: string, input: z.output<typeof updateRoleInputSchema>): Promise<RoleView>;
+    deleteRole(id: string): Promise<void>;
+    cloneRole(id: string, input: z.output<typeof cloneRoleInputSchema>): Promise<RoleView>;
+    private principalNames;
+    private domainNames;
+    listAssignments(domain: AccessDomain | null, query: z.output<typeof assignmentQuerySchema>): Promise<AssignmentView[]>;
+    /** Refuses a default role that manages access: every user would. */
+    private assertDefaultMayHold;
+    /** The checks every grant or removal of `role` in `domain` must pass. */
+    private assertMayAssign;
+    createAssignment(input: z.output<typeof createAssignmentInputSchema>): Promise<AssignmentView>;
+    deleteAssignment(id: string): Promise<void>;
+    principals(domain: AccessDomain | null, query: z.output<typeof principalQuerySchema>): Promise<{
+        items: PrincipalEntry[];
+        hasMore: boolean;
+    }>;
+    /** Every permission of another user, with where each one comes from. */
+    explain(userId: string, domain: AccessDomain | null): Promise<ExplainView>;
+    settings(): Promise<SettingsView>;
+    updateSettings(input: z.output<typeof updateSettingsInputSchema>): Promise<SettingsView>;
+    audit(query: z.output<typeof auditQuerySchema>): Promise<{
+        items: AuditEntryView[];
+        hasMore: boolean;
+    }>;
+}
+
+/**
+ * The catalog's JSON Schema, for editors.
+ *
+ * Shipped as `@tego/plugin-sdk/access-catalog.schema.json`; an `access.json`
+ * pointing its `$schema` there gets completion and inline errors. The schema
+ * only covers shape — cross-references are checked by the pack step.
+ */
+declare function accessCatalogJsonSchema(): Record<string, unknown>;
+
+export { AccessAdmin, AccessAdminError, type AccessAssignment, AccessCatalog, type AccessChange, AccessDeniedError, type AccessDomain, AccessEngine, type AccessHooks, type AccessRole, AccessSession, type AccessSettingsRow, type AccessSnapshot, type AccessSubject, type AssignmentPrincipal, type AssignmentView, type AuditEntry, type AuditEntryView, BUILTIN_SCOPES, type CheckOptions, type CreateAccessOptions, type Decision, type DecisionReason, DelegationAction, type DomainInheritance, type DomainSource, EffectiveGrants, type ExplainView, FALSE_FRAGMENT, type GrantSource, type GrantSourceKind, GrantValue, Grants, PermissionOf, type PrincipalEntry, type PrincipalMembership, type PrincipalQuery, type PrincipalSource, type Queryable, type ReconcileReport, type ResolveInput, type RoleView, type ScopeContext, type ScopeEvaluator, type ScopeRef, type SettingsView, type SqlFragment, TRUE_FRAGMENT, TypedAccessCatalog, accessCatalogJsonSchema, allScope, assignmentInDomain, assignmentMatches, assignmentQuerySchema, auditQuerySchema, bindFragment, cloneRoleInputSchema, createAccess, createAssignmentInputSchema, createRoleInputSchema, decideResource, domainInputSchema, domainKey, ident, orFragments, ownScope, principalQuerySchema, refColumn, renderFragment, resolveGrants, sql, subjectFromContext, uncoveredGrants, unitPrincipalSource, updateRoleInputSchema, updateSettingsInputSchema, userPrincipalSource, validGrants };