permdock 0.3.1 → 0.5.0

package/dist/index-BNc7Wer_.d.ts

@@ -1,483 +0,0 @@
-import { $ as AccessEvent, C as Policy, D as PolicyVocabulary, Dr as CustomRole, Gr as SqlFunctionArg, Kr as SqlFunctionCondition, Lr as ConditionRef, Mr as Membership, Nr as Principal, Pr as Subject, Tt as Snapshot, Vr as OpaqueCondition, Zn as DenialReason, bt as RelationSource, dt as LimitStore, gt as MembershipSource, h as Grant, kr as Delegation, ln as PermDock, pt as LocalSnapshotManifest, rt as DecisionEvent, st as EntitlementSource, w as PolicyDelegation, xt as RoleSource } from "./policy-IB6yxpC3.js";
-import { C as ResourceRelationInput, f as Permission, m as PermissionTree, n as ActionMeta, t as ActionList, w as ResourceRestricted, x as ResourceParent } from "./permissions-DttnqqxC.js";
-//#region src/core/custom-roles.d.ts
-type CustomRoleDropReason = "unknown-permission" | "outside-ceiling" | "condition-not-allowed" | "unknown-level";
-/** Why part of a custom role was left out: a permission, or an undeclared include. */
-type CustomRoleDrop = {
-  readonly permission: string;
-  readonly reason: CustomRoleDropReason;
-  /** The stored level, for `unknown-level`. */
-  readonly level?: string;
-} | {
-  readonly role: string;
-  readonly reason: "unknown-role";
-};
-/** A stored grant that named a permission by a key it was renamed from. */
-type CustomRoleRename = {
-  readonly from: string;
-  readonly to: string;
-};
-type ResolvedCustomRole = {
-  /** Declared grants re-targeted to the custom role; conditions and approvals kept. */
-  readonly grants: readonly Grant[];
-  readonly dropped: readonly CustomRoleDrop[];
-  /** Grants stored under a former key (`definePermissions` `renamed`), resolved to the current one. */
-  readonly renamed: readonly CustomRoleRename[];
-};
-type CustomRoleValidation = {
-  readonly ok: boolean;
-  /** Permission keys the role allows after the ceiling, sorted. */
-  readonly permissions: readonly string[];
-  readonly dropped: readonly CustomRoleDrop[];
-  /** Grants to rewrite in storage: each still resolves, under its current key. */
-  readonly renamed: readonly CustomRoleRename[];
-};
-/**
- * The one resolver behind evaluation, snapshots and `validateCustomRole`.
- * Included roles' grants plus the role's own allows, minus its denies, all
- * intersected with the ceiling. An allow inherits the condition, approval and
- * limit of the declared grant it comes from: an included assignable role's
- * grant when there is one, otherwise every ceiling grant of that permission,
- * together with the denies of the roles those grants belong to.
- */
-declare function resolveCustomRole(policy: Policy, role: CustomRole): ResolvedCustomRole;
-declare function validateCustomRole(policy: Policy, role: CustomRole): CustomRoleValidation;
-/**
- * The compact JWT form of custom roles for the `memberships[].grants` claim
- * RLS reads in `jwt` mode: role name to entries, where `key` allows, `-key`
- * denies and `@role` includes. Put a team custom role on its team membership.
- * Pass `policy` to write keys stored under a former name as the current key.
- */
-declare function customRoleClaim(roles: readonly CustomRole[], policy?: Policy): Readonly<Record<string, readonly string[]>>;
-//#endregion
-//#region src/core/relations.d.ts
-type MemoryEdge = {
-  /** The object's id. */
-  readonly id: string;
-  readonly principal: string;
-  readonly startsAt?: number;
-  readonly expiresAt?: number;
-};
-type MemoryRelationsData = {
-  /** Rows per resource: parent pointers, links, restricted flags and relation columns are read from them. */
-  readonly rows?: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
-  /** Edge-table rows per resource and relation. */
-  readonly edges?: Readonly<Record<string, Readonly<Record<string, readonly MemoryEdge[]>>>>;
-  /**
-   * Edge tables as the database holds them, keyed by `edge` name: each row
-   * is read through the relation's `object`, `subject`, `expiresAt`, `match`
-   * and `groups` columns. A relation whose table is here ignores `edges`.
-   */
-  readonly tables?: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
-};
-/**
- * An in-process `RelationSource` over plain rows and edges, read against the
- * resource definitions in `permissions`. For tests, fixtures and small apps.
- */
-declare function memoryRelations(permissions: PermissionTree, data?: MemoryRelationsData): RelationSource;
-//#endregion
-//#region src/core/snapshot.d.ts
-declare function parseSnapshot(json: unknown): Snapshot;
-//#endregion
-//#region src/core/from-snapshot.d.ts
-declare function fromSnapshot(snapshot: Snapshot, options?: {
-  readonly tenant?: string;
-  readonly team?: string;
-}): PermDock;
-declare function emptySnapshot(): Snapshot;
-//#endregion
-//#region src/conditions/refs.d.ts
-type KnownRefField = "id" | "issuer" | "kind" | "tenant" | "team" | "roles" | "plans" | "memberships" | "assurance" | "binding" | "session";
-type SubjectRef = ConditionRef & { readonly [K in KnownRefField]: SubjectRef; } & {
-  readonly [key: string]: SubjectRef;
-};
-declare const principal: SubjectRef;
-declare const context: SubjectRef;
-//#endregion
-//#region src/core/approval-required.d.ts
-declare function requiresApproval(approval: Grant["approval"] | undefined): boolean;
-//#endregion
-//#region src/conditions/opaque.d.ts
-declare function opaque(input: {
-  readonly sql: string;
-  readonly fingerprint: string;
-}): OpaqueCondition;
-//#endregion
-//#region src/conditions/sql-function.d.ts
-declare function sqlFunction(name: string, options: {
-  readonly args?: readonly SqlFunctionArg[];
-  readonly twin: unknown;
-}): SqlFunctionCondition;
-//#endregion
-//#region src/core/memberships.d.ts
-/**
- * One `MembershipSource` over several: memberships are merged and
- * de-duplicated, `list` concatenates the sources that can list, and `version`
- * is the highest version any source reports. A source that throws makes the
- * whole lookup throw, which the subject resolver turns into no memberships.
- */
-declare function composeMemberships(sources: readonly MembershipSource[]): MembershipSource;
-/**
- * Trust the memberships the verified token carries, and read `source` only
- * when the token marks them truncated. With `version`, a token minted before
- * the latest membership change is stale for the policy's `fresh` permissions,
- * or with `onStale: 'reread'` has its memberships read from `source` instead.
- */
-declare function claimsFirst(source: MembershipSource | readonly MembershipSource[], options?: {
-  readonly version?: MembershipSource["version"];
-  readonly onStale?: "deny" | "reread";
-}): MembershipSource;
-/** Whether the identity provider owns `membership`: the application must not add, change or remove it. */
-declare function isExternallyManaged(membership: Membership): boolean;
-/**
- * How many principals hold `role` in one scope instance now, from the
- * source's member list (`MembershipSource.list`): live memberships of exactly
- * that scope and instance, each principal counted once. The `holders` a
- * `decideRoleChange` with `min`, `max` or `transferOnly` needs. `undefined`
- * when the source cannot list or the read fails, which that check denies.
- */
-declare function countHolders(source: MembershipSource | readonly MembershipSource[], query: {
-  readonly scope: string;
-  readonly id: string;
-  readonly role: string | {
-    readonly key: string;
-  };
-}): Promise<number | undefined>;
-//#endregion
-//#region src/core/stripe-entitlements.d.ts
-/** The part of the Stripe Node SDK this source calls: `stripe.entitlements.activeEntitlements.list`. */
-type StripeEntitlementsClient = {
-  readonly entitlements: {
-    readonly activeEntitlements: {
-      list(params: {
-        readonly customer: string;
-        readonly limit?: number;
-        readonly starting_after?: string;
-      }): PromiseLike<{
-        readonly data: readonly {
-          readonly id: string;
-          readonly lookup_key: string;
-        }[];
-        readonly has_more: boolean;
-      }>;
-    };
-  };
-};
-/**
- * Plan names from Stripe Entitlements: the `lookup_key` of every active
- * entitlement of the tenant's Stripe customer. `customer` maps the active
- * tenant to its customer id; no tenant or no customer means no entitlements.
- * Pass it as `entitlements`, and grant with `plan('<lookup_key>')`.
- */
-declare function fromStripeEntitlements(options: {
-  readonly stripe: StripeEntitlementsClient;
-  readonly customer: (tenant: string, principal: {
-    readonly id: string;
-  }) => string | undefined | PromiseLike<string | undefined>;
-}): EntitlementSource;
-//#endregion
-//#region src/core/limits.d.ts
-declare function memoryLimitStore(): LimitStore & {
-  /** Live counters, for tests and diagnostics. */
-  size(): number;
-};
-//#endregion
-//#region src/core/local-manifest.d.ts
-/**
- * What the policy grants, as JSON a device turns into snapshots from its own
- * membership rows (`localSnapshot` in `permdock/react-native`). Write it at
- * build time; the policy itself never ships to the client.
- */
-declare function localSnapshotManifest(policy: Policy): LocalSnapshotManifest;
-//#endregion
-//#region src/core/may-access.d.ts
-/**
- * An optimistic routing hint for a proxy or middleware, never a decision.
- * `false` only when the subject's declared roles provably lack `permission`;
- * `true` whenever custom roles, plans, memberships the claims do not carry or
- * row conditions could still grant it. Synchronous, no network, never throws.
- * Pages, Server Actions and RLS remain the enforcement points.
- */
-declare function mayAccess(policy: Policy, user: unknown, permission: Permission, options?: {
-  readonly tenant?: string;
-}): boolean;
-//#endregion
-//#region src/core/may-use.d.ts
-/**
- * Whether `permission` could be granted to this instance's subject for some
- * row: the grants its snapshot carries for the active tenant, minus an
- * unconditional deny, within its delegation. A listing hint for tools and
- * skills, never a decision; the call itself is decided in full.
- */
-declare function mayUse(permdock: PermDock, permission: Permission): boolean;
-type PermittedIdsOptions = {
-  readonly within?: string;
-  readonly conditioned?: boolean;
-};
-/**
- * The instances of `scope` in which the subject holds `permission`, from its
- * live memberships of exactly that scope, within its delegation: by default
- * those with an allow that carries no row condition (`where`, `check`, a
- * validity window or a non-portable test; a `fields` limit is not a row
- * condition), minus the instances any deny of the permission reaches. The
- * in-process mirror of the SQL `permitted_<scope>_ids_by_permission`. With
- * `conditioned: true` it also lists the instances where a conditioned allow
- * applies, minus only unconditional denies, as
- * `permitted_<scope>_ids_by_permission(p_permission, true)` does. A listing,
- * never a decision: a row's own check still runs `can`.
- */
-declare function permittedIds(permdock: PermDock, permission: Permission, scope: string, options?: PermittedIdsOptions): readonly string[];
-//#endregion
-//#region src/core/custom-role-source.d.ts
-/** Reads custom roles from the application's store, as `customRoleSource` takes them. */
-type CustomRoleReader = {
-  /** Every custom role of `tenant`, whether or not anyone in the request holds it. */
-  rolesOf(tenant: string): CustomRole[] | Promise<CustomRole[]>;
-  assignable?(tenant: string): string[] | Promise<string[]>;
-  /** Platform custom roles (`scope: 'global'`). */
-  globalRoles?(): CustomRole[] | Promise<CustomRole[]>;
-};
-type CustomRoleSourceOptions = {
-  /** `'all'` (default): read every custom role of each tenant, so `assignableRoles` and `decideRoleChange` see them all. */
-  readonly read?: "all";
-} | {
-  /** `'held'`: skip a tenant's read, and the platform read, when every role the subject holds there is declared in `policy`. For requests that never manage roles. */
-  readonly read: "held";
-  readonly policy: Policy;
-};
-/**
- * A `RoleSource` over a reader that returns every custom role of a tenant.
- * It keeps only the roles of the requested tenant. With `read: 'held'` it
- * skips a tenant's read, and `globalRoles`, when the subject holds only
- * declared roles there.
- */
-declare function customRoleSource(reader: CustomRoleReader, options?: CustomRoleSourceOptions): RoleSource;
-//#endregion
-//#region src/core/instance.d.ts
-type SnapshotInclude = readonly (Permission | {
-  readonly [key: string]: unknown;
-})[];
-//#endregion
-//#region src/core/snapshot-for.d.ts
-type SnapshotForOptions = {
-  /** Active tenant; ignored unless the subject holds a membership in it. */
-  readonly tenant?: string;
-  /** Database mode: replaces the memberships carried by the subject. */
-  readonly memberships?: readonly Membership[];
-  /** The tenant's custom roles, typically from a shared, tagged cache. */
-  readonly customRoles?: readonly CustomRole[];
-  /** Per tenant, the role names `RoleSource.assignable` returns; narrows `assignable`. */
-  readonly assignable?: Readonly<Record<string, readonly string[]>>;
-  /** Plans of the active tenant; replaces `principal.plans`. */
-  readonly plans?: readonly string[];
-  readonly include?: SnapshotInclude;
-  readonly tenants?: "all";
-  /** Epoch seconds for `issuedAt` and membership expiry. Defaults to the clock. */
-  readonly now?: number;
-};
-/**
- * Builds the serializable access snapshot for a subject without a request,
- * a network call or a cache directive: call it inside the app's own
- * `'use cache: private'` function. Synchronous; the policy's `subject` and
- * `context` mappers must be synchronous too.
- */
-declare function snapshotFor<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, user: TUser | Subject | null, options?: SnapshotForOptions): Snapshot;
-//#endregion
-//#region src/core/presets.d.ts
-type ReadOnlyMeta = {
-  readonly readOnly: true;
-};
-type DestructiveMeta = {
-  readonly destructive: true;
-};
-type CrudActions = {
-  readonly read: ReadOnlyMeta;
-  readonly update: ActionMeta;
-  readonly delete: DestructiveMeta;
-};
-type CrudCollection = {
-  readonly create: ActionMeta;
-  readonly list: ReadOnlyMeta;
-};
-type ReadableActions = {
-  readonly read: ReadOnlyMeta;
-};
-type ReadableCollection = {
-  readonly list: ReadOnlyMeta;
-};
-type WritableActions = {
-  readonly read: ReadOnlyMeta;
-  readonly update: ActionMeta;
-};
-declare const CRUD_ACTIONS: CrudActions;
-declare const CRUD_COLLECTION: CrudCollection;
-declare const READABLE_ACTIONS: ReadableActions;
-declare const READABLE_COLLECTION: ReadableCollection;
-declare const WRITABLE_ACTIONS: WritableActions;
-type EmptyRecord = Record<never, never>;
-declare const WRITABLE_COLLECTION: EmptyRecord;
-type ActionNames<A extends ActionList | undefined> = A extends readonly string[] ? A[number] & string : A extends Record<string, ActionMeta> ? keyof A & string : never;
-type ToActionRecord<A extends ActionList | undefined> = [ActionNames<A>] extends [never] ? EmptyRecord : { readonly [K in ActionNames<A>]: ActionMeta; };
-type OverlayMeta<Base extends ActionMeta, Extra extends ActionMeta> = Omit<Base, keyof Extra> & Extra;
-type MergeActionRecords<Base extends Record<string, ActionMeta>, Extra extends Record<string, ActionMeta>> = { readonly [K in keyof Base | keyof Extra]: K extends keyof Extra ? K extends keyof Base ? OverlayMeta<Base[K] & ActionMeta, Extra[K] & ActionMeta> : Extra[K] & ActionMeta : K extends keyof Base ? Base[K] & ActionMeta : never; };
-type PresetOptions<A extends ActionList | undefined = undefined, C extends ActionList | undefined = undefined> = {
-  readonly id?: string;
-  readonly parent?: ResourceParent;
-  readonly relations?: Readonly<Record<string, ResourceRelationInput>>;
-  readonly restricted?: string | ResourceRestricted;
-  readonly disclosure?: "hide" | "reveal";
-  readonly actions?: A;
-  readonly collection?: C;
-};
-type PresetResult<BaseA extends Record<string, ActionMeta>, BaseC extends Record<string, ActionMeta>, A extends ActionList | undefined, C extends ActionList | undefined> = {
-  readonly id?: string;
-  readonly parent?: ResourceParent;
-  readonly relations?: Readonly<Record<string, ResourceRelationInput>>;
-  readonly restricted?: string | ResourceRestricted;
-  readonly disclosure?: "hide" | "reveal";
-  readonly actions: MergeActionRecords<BaseA, ToActionRecord<A>>;
-  readonly collection?: MergeActionRecords<BaseC, ToActionRecord<C>>;
-};
-declare function crud<const A extends ActionList | undefined = undefined, const C extends ActionList | undefined = undefined>(options?: PresetOptions<A, C>): PresetResult<typeof CRUD_ACTIONS, typeof CRUD_COLLECTION, A, C>;
-declare function readable<const A extends ActionList | undefined = undefined, const C extends ActionList | undefined = undefined>(options?: PresetOptions<A, C>): PresetResult<typeof READABLE_ACTIONS, typeof READABLE_COLLECTION, A, C>;
-declare function writable<const A extends ActionList | undefined = undefined, const C extends ActionList | undefined = undefined>(options?: PresetOptions<A, C>): PresetResult<typeof WRITABLE_ACTIONS, typeof WRITABLE_COLLECTION, A, C>;
-//#endregion
-//#region src/core/duration.d.ts
-declare function parseDuration(input: unknown): number | undefined;
-//#endregion
-//#region src/core/ocsf.d.ts
-/** The OCSF schema version `toOcsf` emits. */
-declare const OCSF_VERSION = "1.3.0";
-/** An OCSF Authorize Session (class 3003, category Identity and Access Management) event. */
-type OcsfAuthorizeSession = {
-  readonly class_uid: 3003;
-  readonly category_uid: 3;
-  readonly activity_id: 1;
-  readonly type_uid: 300301;
-  readonly severity_id: 1 | 4;
-  readonly time: number;
-  readonly status_id: 0 | 1 | 2 | 99;
-  readonly status: "Unknown" | "Success" | "Failure" | "Other";
-  readonly status_detail?: string;
-  readonly message: string;
-  readonly privileges: readonly string[];
-  /** OCSF requires `user`; an anonymous subject is `{ name: 'anonymous' }`. */
-  readonly user: {
-    readonly uid: string;
-  } | {
-    readonly name: "anonymous";
-  };
-  readonly actor?: {
-    readonly user?: {
-      readonly uid: string;
-    };
-    readonly app_name?: string;
-  };
-  readonly metadata: {
-    readonly version: typeof OCSF_VERSION;
-    readonly product: {
-      readonly name: "PermDock";
-      readonly vendor_name: "PermDock";
-      readonly feature?: {
-        readonly name: string;
-      };
-    };
-    readonly tenant_uid?: string;
-    readonly correlation_uid?: string;
-  };
-  readonly unmapped: {
-    readonly outcome: DecisionEvent["outcome"];
-    readonly scope: string;
-    readonly resource: DecisionEvent["resource"];
-    readonly source: DecisionEvent["source"];
-    readonly phase?: DecisionEvent["phase"];
-    readonly role?: string | null;
-    readonly via?: string | null;
-    /** Set high-severity break-glass events apart in a SIEM. */
-    readonly breakGlass?: true;
-    readonly purpose?: readonly string[];
-    readonly reason?: string;
-  };
-};
-/** Projects a decision or approval event onto OCSF Authorize Session; the event itself is unchanged. */
-declare function toOcsf(event: DecisionEvent): OcsfAuthorizeSession;
-/**
- * An OCSF Account Change (class 3001) event for a support-access lifecycle
- * event: `started` enables the session, `ended` and `revoked` disable it.
- * Support access is high severity, so a SIEM can alert on vendor access.
- */
-type OcsfAccountChange = {
-  readonly class_uid: 3001;
-  readonly category_uid: 3;
-  /** 2 Enable for `started`, 5 Disable for `ended` and `revoked`. */
-  readonly activity_id: 2 | 5;
-  readonly type_uid: 300102 | 300105;
-  readonly severity_id: 4;
-  readonly time: number;
-  readonly message: string;
-  readonly user: {
-    readonly uid: string;
-  };
-  readonly actor?: {
-    readonly user?: {
-      readonly uid: string;
-    };
-  };
-  readonly metadata: {
-    readonly version: typeof OCSF_VERSION;
-    readonly product: {
-      readonly name: "PermDock";
-      readonly vendor_name: "PermDock";
-    };
-    readonly tenant_uid: string;
-  };
-  readonly unmapped: {
-    readonly operation: AccessEvent["operation"];
-    readonly via: string;
-    readonly roles: readonly string[];
-    readonly member?: {
-      readonly group: string;
-    };
-    readonly grantedBy?: string;
-    readonly reason?: string;
-  };
-};
-declare function accessToOcsf(event: AccessEvent): OcsfAccountChange;
-//#endregion
-//#region src/core/csv.d.ts
-/** The CSV export columns, in order; the header row of every CSV file. */
-declare const CSV_COLUMNS: readonly ["time", "principal", "actor", "tenant", "permission", "outcome", "matched.role", "via", "denials.reason", "token"];
-/**
- * One RFC 4180 row for a decision or approval event, without a line
- * terminator; join rows with CRLF under a `CSV_COLUMNS` header.
- */
-declare function toCsvRow(event: DecisionEvent): string;
-//#endregion
-//#region src/core/catalog-fingerprint.d.ts
-/**
- * The catalog v1 fingerprint: base64url SHA-256 of canonical JSON (keys
- * sorted, no whitespace) without `generatedAt`, `generator`, `fingerprint`
- * and every `permissions[].usages`, so neither the CLI version, the clock nor
- * call sites change it.
- */
-declare function catalogFingerprint(catalog: unknown): string;
-//#endregion
-//#region src/core/delegation.d.ts
-type DelegatedPermission = Pick<Permission, "scope" | "resource" | "action">;
-/**
- * Whether a delegated caller may use a permission its principal holds, through
- * OAuth `scopes`, RFC 9396 `authorizationDetails` or GNAP `access`.
- * `undefined` means covered; otherwise the denial reason `decide` would add.
- */
-declare function coveredByDelegation(permission: DelegatedPermission, delegation: Delegation | undefined, resourceId?: string, hasActor?: boolean): DenialReason | undefined;
-/**
- * The permission keys the policy's delegations let `subject.actor` use for
- * `subject.principal` right now: the union over every active delegation whose
- * `to` matches the actor and whose `from` the principal holds. `undefined`
- * when none applies, so the call falls back to the token delegation alone.
- * An actor with `readOnly: true` gets only each delegation's read-only keys.
- * Attenuation only: a key here still needs a matching allow and no deny.
- */
-declare function delegatedPermissions(delegations: readonly PolicyDelegation[] | undefined, subject: Subject, heldRoles: ReadonlySet<string>, now: number): ReadonlySet<string> | undefined;
-//#endregion
-export { countHolders as A, MemoryEdge as B, mayAccess as C, fromStripeEntitlements as D, StripeEntitlementsClient as E, context as F, CustomRoleRename as G, memoryRelations as H, principal as I, customRoleClaim as J, CustomRoleValidation as K, emptySnapshot as L, sqlFunction as M, opaque as N, claimsFirst as O, requiresApproval as P, fromSnapshot as R, permittedIds as S, memoryLimitStore as T, CustomRoleDrop as U, MemoryRelationsData as V, CustomRoleDropReason as W, validateCustomRole as X, resolveCustomRole as Y, CustomRoleReader as _, toCsvRow as a, PermittedIdsOptions as b, OcsfAuthorizeSession as c, parseDuration as d, crud as f, snapshotFor as g, SnapshotForOptions as h, CSV_COLUMNS as i, isExternallyManaged as j, composeMemberships as k, accessToOcsf as l, writable as m, delegatedPermissions as n, OCSF_VERSION as o, readable as p, ResolvedCustomRole as q, catalogFingerprint as r, OcsfAccountChange as s, coveredByDelegation as t, toOcsf as u, CustomRoleSourceOptions as v, localSnapshotManifest as w, mayUse as x, customRoleSource as y, parseSnapshot as z };