permdock 0.0.0 → 0.2.0

package/dist/types-yF5LmQVD.d.ts

@@ -0,0 +1,306 @@
+import { Nr as Principal, et as AuthEvent } from "./policy-CFZAr_Al.js";
+import { t as ClientNames } from "./clients-C7zLFuWT.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/supabase/claims.d.ts
+/** One entry of the `memberships` claim, as `schemas/supabase-claims-v1.json` defines it. */
+type SupabaseMembershipClaim = {
+  readonly scope?: string;
+  /** Canonical text of the scope instance id, compared exactly. */
+  readonly id?: string;
+  /** The id of every ancestor scope instance, by scope name. */
+  readonly within?: Readonly<Record<string, string>>;
+  readonly on?: {
+    readonly resource: string;
+    readonly id: string;
+  };
+  readonly tenant?: string;
+  readonly team?: string;
+  readonly roles: readonly string[];
+  readonly via?: string;
+  /** Seconds since the epoch. */
+  readonly expiresAt?: number;
+  readonly grantedBy?: string;
+  readonly reason?: string;
+  /** The subgroup a membership source's `group` fills: a fixed name or a column. */
+  readonly member?: {
+    readonly group: string;
+  };
+  readonly managedBy?: "idp";
+  readonly entitlements?: readonly string[];
+  /** The instance or an ancestor is suspended: the permission keys the membership still grants. */
+  readonly keep?: readonly string[];
+  /** Custom roles in compact form, read by the RLS helpers in `jwt` mode. */
+  readonly grants?: Readonly<Record<string, unknown>>;
+};
+/** An RFC 8693 `act` claim: the acting party, optionally acting for another. */
+type SupabaseActClaim = {
+  readonly sub?: string;
+  readonly act?: SupabaseActClaim;
+  readonly [claim: string]: unknown;
+};
+/** The claims the hook writes; each may also sit under `app_metadata`. */
+type SupabasePermDockClaims<TenantClaim extends string = "tenant_id"> = {
+  /** Global roles: one name, a list, or `null` for none. */
+  readonly user_role?: string | readonly string[] | null;
+  readonly roles?: readonly string[];
+  readonly memberships?: readonly SupabaseMembershipClaim[];
+  /** `true` when the size budget cut `memberships` or `attrs`. */
+  readonly memberships_truncated?: boolean;
+  /** Allow-listed server-owned attributes, read as `principal.claims.attrs.<key>`. */
+  readonly attrs?: Readonly<Record<string, unknown>>;
+  /** The principal's authorization version. */
+  readonly authz_ver?: number;
+} & { readonly [K in TenantClaim]?: string; };
+/**
+ * A Supabase access token in PermDock's claim contract
+ * (`schemas/supabase-claims-v1.json`). Claims it does not name pass through.
+ */
+type SupabaseClaims<TenantClaim extends string = "tenant_id"> = SupabasePermDockClaims<TenantClaim> & {
+  /** The OAuth client of a third-party app (Supabase OAuth server). */
+  readonly client_id?: string;
+  /** OAuth scopes, space-separated or as a list. */
+  readonly scope?: string | readonly string[];
+  readonly act?: SupabaseActClaim;
+  readonly app_metadata?: SupabasePermDockClaims<TenantClaim> & {
+    readonly [claim: string]: unknown;
+  };
+  readonly [claim: string]: unknown;
+};
+/**
+ * A Standard Schema v1 over {@link SupabaseClaims}. `extend(app)` adds an
+ * application's own claim schema: both validate the same claims, their issues
+ * are combined, and the app's output is merged over the base.
+ */
+type SupabaseClaimsSchema<TenantClaim extends string = "tenant_id", Extra = unknown> = StandardSchemaV1<unknown, SupabaseClaims<TenantClaim> & Extra> & {
+  extend<App extends StandardSchemaV1>(app: App): SupabaseClaimsSchema<TenantClaim, Extra & StandardSchemaV1.InferOutput<App>>;
+};
+type SupabaseClaimsOptions<TenantClaim extends string = "tenant_id"> = {
+  /** The claim holding the active tenant; `rls.tenantClaim`, default `tenant_id`. */
+  readonly tenantClaim?: TenantClaim;
+};
+/**
+ * A Standard Schema v1 for PermDock's Supabase claims. Unknown claims pass
+ * through unchanged; a known claim with the wrong shape is an issue, so the
+ * whole token is rejected as `schemas/supabase-claims-v1.json` rejects it.
+ * Needs no validation library.
+ *
+ * ```ts
+ * sb.claims(supabaseClaims().extend(z.object({ datetime_preferences: Prefs })))
+ * ```
+ */
+declare function supabaseClaims<TenantClaim extends string = "tenant_id">(options?: SupabaseClaimsOptions<TenantClaim>): SupabaseClaimsSchema<TenantClaim>;
+//#endregion
+//#region src/supabase/types.d.ts
+type SupabasePrincipal = Principal & {
+  readonly claims?: Readonly<Record<string, unknown>>;
+  readonly email?: string;
+  readonly phone?: string;
+  readonly is_anonymous?: boolean;
+};
+type SupabaseInclude = "email" | "phone" | "is_anonymous";
+/**
+ * A column that holds a foreign key: the value is `column` of `through`,
+ * joined on `on`. A role reads its key from a roles table
+ * (`{ through: 'roles', on: { role_id: 'id' }, column: 'key' }`); a
+ * membership source's user can read its user id from a profile table
+ * (`{ through: 'contact_profiles', on: { contact_profile_id: 'id' }, column: 'user_id' }`).
+ */
+type RoleThrough = {
+  /** The referenced table; unqualified, it is in the schema of the table that references it. */
+  readonly through: string;
+  /** One entry: the referencing column to the column of `through` it references. */
+  readonly on: Readonly<Record<string, string>>;
+  /** The column of `through` that holds the value: the role key, or the user id. */
+  readonly column: string;
+};
+type SupabaseMembershipTable = {
+  readonly table: string;
+  readonly user: string;
+  /**
+   * The role key column, a reference to a roles table that holds the key, or
+   * several of them: the row holds every non-null key.
+   */
+  readonly role: string | RoleThrough | readonly (string | RoleThrough)[];
+  /** Per scope name, the column holding that scope's id: the table's own scope and its ancestors. */
+  readonly columns?: Readonly<Record<string, string>>;
+  readonly tenant?: string;
+  readonly team?: string;
+  readonly id?: string;
+  readonly expiresAt?: string;
+  readonly disabledAt?: string;
+};
+/** A table whose row says whether a user or a scope instance is active. A missing row counts as suspended. */
+type SupabaseActiveRow = {
+  readonly table: string;
+  /** Column holding the user id or the scope instance id. */
+  readonly id: string;
+  /** Nullable timestamp column; a row with a value is suspended. */
+  readonly disabledAt?: string;
+  /** Status column; only a row whose value is in `active` counts as active. */
+  readonly status?: string;
+  readonly active?: readonly string[];
+};
+/** A scope's active-row table, with the permissions its suspended instances keep. */
+type SupabaseSuspendedScope = SupabaseActiveRow & {
+  /**
+   * Permissions (references or keys) members of a suspended instance, and of
+   * every instance nested in it, still hold; such a membership carries them
+   * as `keep`.
+   */
+  readonly keep?: readonly (string | {
+    readonly key: string;
+  })[];
+};
+type SupabaseSuspendedMembership = {
+  readonly keep?: readonly (string | {
+    readonly key: string;
+  })[];
+};
+type SupabaseSuspension = {
+  /** A suspended user holds no role and no membership. */
+  readonly users?: SupabaseActiveRow;
+  /** Per scope name: a suspended instance voids its memberships and every membership nested under it, except for `keep`. */
+  readonly scopes?: Readonly<Record<string, SupabaseSuspendedScope>>;
+  readonly memberships?: SupabaseSuspendedMembership;
+};
+type SupabaseMemberships = {
+  /** The membership table of each named scope. */
+  readonly scopes?: Readonly<Record<string, SupabaseMembershipTable>>;
+  readonly tenant?: SupabaseMembershipTable;
+  readonly team?: SupabaseMembershipTable;
+  readonly resource?: Readonly<Record<string, SupabaseMembershipTable>>;
+};
+type AuthorizeSqlOptions = {
+  /** Postgres schema of `authorize`, `user_roles`, `role_permissions` and `app_permission`. Default `permdock`. */
+  readonly schema?: string;
+  /** `database` (default) reads the tables on every call; `jwt` reads the hook-injected claims. */
+  readonly authorize?: "database" | "jwt";
+  /** The policy's first scope, which `requested_tenant` is an instance of. Default `tenant`. */
+  readonly scope?: string;
+  /** Membership table for tenant requests in `database` mode; without one they deny. */
+  readonly tenant?: boolean | SupabaseMembershipTable;
+  /**
+   * Tenant requests also answer from custom roles, through the `permdock_custom_keys` function
+   * `permdock rls generate --custom-roles` emits: the `custom_role_*` tables in `database` mode,
+   * the `memberships[].grants` claim in `jwt` mode. `declared` role names never resolve as custom.
+   */
+  readonly customRoles?: {
+    readonly declared: readonly string[];
+    /** Stored allows may carry a level (`custom_role_permissions.level`). */
+    readonly levels?: true;
+  };
+  /** A suspended user, or a suspended instance of `scope` for a tenant request, answers `false`. */
+  readonly suspension?: SupabaseSuspension;
+};
+/** A permission reference; `rls generate` reads only its `key`. */
+type SupabasePermissionRef = {
+  readonly key: string;
+};
+/**
+ * Private Realtime channels: topic patterns such as `org:{organization}:chat`,
+ * with one `{<scope>}` segment that holds a scope instance id.
+ */
+type SupabaseRealtime = {
+  readonly topics: Readonly<Record<string, {
+    /** Receive broadcast and presence: `select` on `realtime.messages`. */
+    readonly read: SupabasePermissionRef;
+    /** Send broadcast and track presence: `insert`. */
+    readonly write?: SupabasePermissionRef;
+  }>>;
+};
+/** Storage buckets whose object paths hold a scope instance id in folder `folder` (default 1). */
+type SupabaseStorage = {
+  readonly buckets: Readonly<Record<string, {
+    readonly scope: string;
+    readonly folder?: number;
+    readonly read?: SupabasePermissionRef;
+    readonly write?: SupabasePermissionRef;
+    readonly delete?: SupabasePermissionRef;
+  }>>;
+};
+type SupabaseRlsOptions = {
+  readonly roleClaim?: string;
+  readonly tenantClaim?: string;
+  /** Postgres type of tenant columns; the tenant claim is cast to it. `rls generate` defaults to `uuid`. */
+  readonly tenantType?: string;
+  readonly memberships?: SupabaseMembershipTable | SupabaseMemberships;
+  readonly suspension?: SupabaseSuspension;
+  readonly realtime?: SupabaseRealtime;
+  readonly storage?: SupabaseStorage;
+};
+type SupabaseRlsConfig = {
+  readonly dialect: "supabase";
+  readonly roleClaim: string;
+  readonly tenantClaim: string;
+  readonly tenantType?: string;
+  readonly memberships?: SupabaseMemberships;
+  readonly suspension?: SupabaseSuspension;
+  readonly realtime?: SupabaseRealtime;
+  readonly storage?: SupabaseStorage;
+};
+/**
+ * The structural shape `subjectFromSupabaseSession` reads: a discriminant and the verified JWT claims.
+ * Matches any session object of that shape without importing its library.
+ */
+type SupabaseSessionLike = {
+  readonly kind: string;
+  readonly claims?: unknown;
+};
+type SupabaseSubjectOptions = {
+  readonly roles?: string;
+  readonly tenant?: string;
+  readonly memberships?: string;
+  readonly schema?: StandardSchemaV1;
+  readonly include?: readonly SupabaseInclude[];
+  readonly declared?: readonly string[];
+  /** Claim holding plan names per tenant id; the active tenant's entry becomes `principal.plans`. */
+  readonly plans?: string;
+  /** Names for OAuth client ids: an `oauth-client` actor gets `client` set to the name of its id, which a policy delegation matches with `to: { kind: 'oauth-client', client }`. */
+  readonly clients?: ClientNames;
+  /** `'deny'` maps a token with `is_anonymous: true` (`signInAnonymously()`) to the anonymous subject, as `rls.anonymousSignIns: 'deny'` does in RLS. */
+  readonly anonymousSignIns?: "deny";
+  /**
+   * `true` once the caller checked the session against the Auth server for this request
+   * (`auth.getUser()` or an equivalent session check): a token with a `session_id` gets
+   * `subject.liveSession`, which `{ subject: { session: { live: true } } }` requires. Never read from claims.
+   */
+  readonly liveSession?: boolean;
+  /** Audit hook: `membership-dropped` for a `memberships` entry that could not be read, `invalid-chain` for a malformed `act`. */
+  readonly onAuth?: (event: AuthEvent) => void;
+};
+/**
+ * Who acts for the user. `oauth-client`: a third-party app or an agent chain (`client_id`, or an
+ * `act` without `kind`). `support`: a support session (`act.kind: "support"` with `session_id`).
+ * `impersonation`: an admin acting as the user (`act.kind: "impersonation"`). `chain` is a copy of
+ * the token's `act` claim when it has one.
+ */
+type SupabaseActor = {
+  readonly id: string;
+  readonly kind: "oauth-client";
+  readonly chain?: SupabaseActClaim;
+} | {
+  readonly id: string;
+  readonly kind: "support";
+  readonly sessionId: string;
+  readonly readOnly: boolean;
+  readonly reason?: string;
+  readonly chain: SupabaseActClaim;
+} | {
+  readonly id: string;
+  readonly kind: "impersonation";
+  readonly reason?: string;
+  readonly chain: SupabaseActClaim;
+};
+/** `actorOf` output: `{ ok: false }` must deny. */
+type SupabaseActorResult = {
+  readonly ok: true;
+  readonly actor?: SupabaseActor;
+} | {
+  readonly ok: false;
+  readonly reason: "invalid-chain";
+};
+type SupabaseDelegation = {
+  readonly scopes: readonly string[];
+};
+//#endregion
+export { SupabaseClaimsSchema as C, supabaseClaims as E, SupabaseClaimsOptions as S, SupabasePermDockClaims as T, SupabaseSuspendedMembership as _, SupabaseActorResult as a, SupabaseActClaim as b, SupabaseMembershipTable as c, SupabaseRealtime as d, SupabaseRlsConfig as f, SupabaseSubjectOptions as g, SupabaseStorage as h, SupabaseActor as i, SupabasePermissionRef as l, SupabaseSessionLike as m, RoleThrough as n, SupabaseDelegation as o, SupabaseRlsOptions as p, SupabaseActiveRow as r, SupabaseInclude as s, AuthorizeSqlOptions as t, SupabasePrincipal as u, SupabaseSuspendedScope as v, SupabaseMembershipClaim as w, SupabaseClaims as x, SupabaseSuspension as y };

package/dist/unplugin/index.d.ts

@@ -0,0 +1,7 @@
+import { a as PermDockPluginOptions } from "../types-BPxgszlT.js";
+import { createUnplugin } from "unplugin";
+//#region src/unplugin/index.d.ts
+type CreateUnplugin = typeof createUnplugin<PermDockPluginOptions | undefined>;
+export declare const createPermDockUnplugin: ReturnType<CreateUnplugin>;
+//#endregion
+export type { PermDockPluginOptions };

package/dist/unplugin/index.js

@@ -0,0 +1,31 @@
+import { n as createCollectScheduler, r as report } from "../watch-UihESpsJ.js";
+import { t as peerHint } from "../peer-BOr_kJE1.js";
+import { createRequire } from "node:module";
+//#region src/unplugin/index.ts
+function loadCreateUnplugin() {
+	try {
+		return createRequire(import.meta.url)("unplugin").createUnplugin;
+	} catch {
+		throw new Error(peerHint("unplugin", "permdock/unplugin"));
+	}
+}
+function collectPlugin(options) {
+	const schedulers = /* @__PURE__ */ new Map();
+	function schedulerFor(cwd) {
+		const scheduler = schedulers.get(cwd) ?? createCollectScheduler(cwd, options);
+		schedulers.set(cwd, scheduler);
+		return scheduler;
+	}
+	return {
+		name: "permdock-collect",
+		async buildStart() {
+			report(await schedulerFor(process.cwd()).run(options?.check === true));
+		},
+		watchChange(id) {
+			schedulerFor(process.cwd()).changed(id);
+		}
+	};
+}
+const createPermDockUnplugin = loadCreateUnplugin()(collectPlugin);
+//#endregion
+export { createPermDockUnplugin };

package/dist/usage-D07N9QJ3.js

@@ -0,0 +1,42 @@
+import { a as listArg, i as globalArgs, t as COMMAND_DESCRIPTIONS } from "./commands-DWOrSQic.js";
+import { defineCommand } from "citty";
+//#region src/cli/commands/usage.ts
+function usage(ctx) {
+	return defineCommand({
+		meta: {
+			name: "usage",
+			description: COMMAND_DESCRIPTIONS.usage
+		},
+		args: {
+			...globalArgs,
+			strict: {
+				type: "boolean",
+				description: "Exit 1 on any finding"
+			},
+			ignore: {
+				type: "string",
+				description: "Permission keys or globs to skip, repeatable",
+				valueHint: "glob"
+			},
+			"dynamic-as-used": {
+				type: "boolean",
+				description: "Count computed permission references as uses"
+			}
+		},
+		async run({ args: parsed, rawArgs }) {
+			const result = await (await import("./usage-D82l1CwK.js")).runUsage({
+				cwd: ctx.cwd,
+				config: ctx.config,
+				ignore: listArg(rawArgs, "ignore"),
+				strict: parsed.strict === true,
+				json: ctx.json,
+				dynamicAsUsed: parsed["dynamic-as-used"] === true,
+				now: ctx.now,
+				io: ctx.io
+			});
+			ctx.report(result);
+		}
+	});
+}
+//#endregion
+export { usage };

package/dist/usage-D82l1CwK.js

@@ -0,0 +1,2 @@
+import { t as runUsage } from "./usage-DG1oeCca.js";
+export { runUsage };