@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/types/namespaces/rls/principal-resolver.d.mts

@@ -0,0 +1,47 @@
+/**
+ * @description Minimal SQL client contract for the principal-subject resolver
+ * @summary Structural subset consumed by `resolvePrincipalForSubject`; any
+ * privileged client able to run parameterized queries (for example a `pg`
+ * `Client` or a TypeORM `QueryRunner`) satisfies it. The resolver requires a
+ * privileged auth-prime/service-role client because the helper function is
+ * `REVOKE`d from `PUBLIC`.
+ * @interface PrincipalSubjectQueryClient
+ */
+export interface PrincipalSubjectQueryClient {
+    /**
+     * @description Executes a parameterized SQL statement
+     * @param {string} sql - The SQL text with positional parameters.
+     * @param {any[]} [values] - Positional parameter values.
+     * @returns {Promise<unknown>} The raw driver result (a rows array or an object with a `rows` array).
+     */
+    query(sql: string, values?: any[]): Promise<unknown>;
+}
+/**
+ * @description Pattern enforcing UUID shape on resolved principals and tenant ids
+ * @summary Used to validate the optional `tenantId` argument and to fail
+ * closed on driver results that are not UUID-shaped strings.
+ * @const PRINCIPAL_UUID_PATTERN
+ */
+export declare const PRINCIPAL_UUID_PATTERN: RegExp;
+/**
+ * @description Resolves the principal UUID for an authenticated subject
+ * @summary Calls the `SECURITY DEFINER` helper
+ * `app_rls_principal_for_subject(text, uuid)` through the given privileged
+ * client with fully parameterized SQL. Fails closed: an empty subject, an
+ * ambiguous subject (the helper returns `NULL` unless exactly one principal
+ * matches), and driver results that are not UUID-shaped strings all resolve to
+ * `undefined` rather than throwing, so callers handle "no principal" uniformly
+ * by denying. Requires a privileged auth-prime/service-role client; this
+ * resolver must never be invoked with an application session client.
+ * @function resolvePrincipalForSubject
+ * @param {PrincipalSubjectQueryClient} client - Privileged client used to run the helper query.
+ * @param {string} subject - The authenticated subject id (`principals.subject_id`).
+ * @param {string} [tenantId] - Optional tenant UUID scoping the lookup.
+ * @returns {Promise<string | undefined>} The principal UUID, or `undefined` when none can be resolved.
+ * @throws {ValidationError} When the client is not query-capable, or `tenantId` is provided but not a UUID.
+ * @example
+ * const principalId = await resolvePrincipalForSubject(pgClient, authSubject, tenantId);
+ * if (!principalId)
+ *   throw new Error("No principal for subject"); // fail closed
+ */
+export declare function resolvePrincipalForSubject(client: PrincipalSubjectQueryClient, subject: string, tenantId?: string): Promise<string | undefined>;

package/lib/types/namespaces/rls/rls-bootstrap.service.d.cts

@@ -0,0 +1,157 @@
+/**
+ * @module integrations/namespaces/rls/bootstrap
+ * @summary Bootstrap service that applies the namespace row-level-security template.
+ * @description Wires the SQL template into a query executor (for example a
+ * `pg.Client`) so deployments apply the policies through application bootstrap
+ * or a migration runner instead of hand-running SQL. Also exposes helpers
+ * that bind `app.principal_id` transaction-locally for request-scoped access.
+ */
+import { ClientBasedService } from "@decaf-ts/core";
+import { InternalError } from "@decaf-ts/db-decorators";
+import type { RlsBootstrapConfig, RlsQueryExecutor, RunAsPrincipalOptions } from "./rls.types.d.cts";
+/**
+ * @description Thrown when the executor role cannot safely own the RLS helper functions.
+ * @summary Raised by
+ * `RlsBootstrapService.assertFunctionOwnerPrivileges()` when the current
+ * database role is neither `SUPERUSER` nor `BYPASSRLS` (or when its
+ * privileges cannot be determined). Extends
+ * `{@link InternalError}` so callers can catch it generically, while
+ * carrying the distinctive `RlsFunctionOwnerError` name for
+ * fail-closed matching.
+ * @class RlsFunctionOwnerError
+ * @category Namespaces
+ */
+export declare class RlsFunctionOwnerError extends InternalError {
+    constructor(message: string);
+}
+/**
+ * @description Options accepted by the transaction-local RLS binding helpers.
+ * @summary Session-wide binding is not supported: the only acceptable value is
+ * `local: true`, which is also the default. A `local: false` request is
+ * rejected with `ValidationError` before any SQL is sent, because a
+ * session-wide setting on a pooled connection leaks across requests.
+ * @interface RlsBindingOptions
+ * @property {true} [local] - Must be `true` or omitted (the default is `true`);
+ * any other value is rejected before any SQL is sent.
+ */
+export interface RlsBindingOptions {
+    local?: true;
+}
+/**
+ * @description Validates a principal identifier before binding it to the
+ * `app.principal_id` RLS setting.
+ * @summary Fail-closed shape guard shared by the binding helpers: the value
+ * must be a non-empty UUID string. On failure it throws a `ValidationError`
+ * with a fixed message that never echoes the rejected value, so invalid input
+ * cannot leak into error surfaces or logs.
+ * @function assertPrincipalId
+ * @param {string} principalId - Candidate principal (or tenant) UUID to validate.
+ * @returns {void}
+ * @throws {ValidationError} When the value is empty or not UUID-shaped; the message does not include the rejected value.
+ */
+export declare function assertPrincipalId(principalId: string): void;
+/**
+ * @description Applies the namespace RLS template through a SQL executor.
+ * @summary The service boots with a SQL executor (`pg.Client`, `pg.Pool`, or a
+ * compatible wrapper) and applies the namespace row-level-security template:
+ * function plus policy DDL executed sequentially. It is the deployment-side
+ * entry point for the RLS template, meant to run during application bootstrap
+ * or a migration runner instead of hand-running SQL. The template is
+ * idempotent and may run on every deployment.
+ * @class RlsBootstrapService
+ * @category Namespaces
+ */
+export declare class RlsBootstrapService extends ClientBasedService<RlsQueryExecutor, RlsBootstrapConfig> {
+    constructor();
+    initialize(...args: any[]): Promise<{
+        config: RlsBootstrapConfig;
+        client: RlsQueryExecutor;
+    }>;
+    /**
+     * @description Applies the configured (or bundled) RLS statement list.
+     * @summary The service is booted with an executor (`pg.Client`, `pg.Pool`, or a
+     * compatible wrapper) and applies function plus policy DDL sequentially. The
+     * template is idempotent and may run on every deployment. Before any DDL is
+     * sent, `assertFunctionOwnerPrivileges()` verifies that the current
+     * executor role is `SUPERUSER` or `BYPASSRLS` and fails closed otherwise,
+     * so `SECURITY DEFINER` helper functions are never created with an owner
+     * that would recurse under `FORCE ROW LEVEL SECURITY`.
+     * @return {Promise<{applied: number}>} The number of statements executed.
+     * @throws {RlsFunctionOwnerError} When the executor role is neither `SUPERUSER` nor `BYPASSRLS`, or its privileges cannot be determined.
+     * @throws {InternalError} When the resolved statement list is empty.
+     */
+    apply(...args: any[]): Promise<{
+        applied: number;
+    }>;
+    /**
+     * @description Verifies that the current executor role can own the RLS helper functions.
+     * @summary Runs `RLS_FUNCTION_OWNER_QUERY` through the configured executor
+     * and reads the current role's `rolsuper`/`rolbypassrls` flags from
+     * `pg_roles`. Fails closed: when the row is missing or the flags are not
+     * booleans, it throws `RlsFunctionOwnerError` with the same
+     * fail-closed semantics as an explicit privilege failure. Called
+     * automatically by `apply()` before any DDL is executed.
+     * @param args - Optional trailing decaf `Context` arguments forwarded to the log context.
+     * @return Resolves when the current role is `SUPERUSER` or `BYPASSRLS`.
+     * @throws {RlsFunctionOwnerError} When the executor role is neither `SUPERUSER` nor `BYPASSRLS`, or when its privileges cannot be determined from `pg_roles`.
+     */
+    assertFunctionOwnerPrivileges(...args: any[]): Promise<void>;
+    /**
+     * @description Resolves the statement list for the active configuration.
+     */
+    statements(): string[];
+    /**
+     * @description Binds the acting principal for the current transaction.
+     * @summary Issues parameterized `SELECT set_config($1, $2, true)` after
+     * validation, so the binding lives only for the current transaction and is
+     * discarded on commit/rollback — safe on pooled connections. A session-wide
+     * binding request fails with `ValidationError` before any SQL is sent, and
+     * the verbose log records only that a binding happened, never the principal
+     * id.
+     * @param principalId Principal UUID stored in `app.principal_id`.
+     * @param options Only `local: true` (the default) is accepted; the binding is
+     * always transaction-local and is discarded on commit/rollback.
+     * @returns {Promise<void>} Resolves once the setting is bound transaction-locally.
+     * @throws {ValidationError} When the principal id is invalid or a session-wide binding is requested.
+     */
+    setPrincipal(principalId: string, options?: RlsBindingOptions, ...args: any[]): Promise<void>;
+    /**
+     * @description Binds the acting tenant for the current transaction.
+     * @summary Issues parameterized `SELECT set_config($1, $2, true)` after
+     * validation, so the binding lives only for the current transaction and is
+     * discarded on commit/rollback — safe on pooled connections. A session-wide
+     * binding request fails with `ValidationError` before any SQL is sent, and
+     * the verbose log records only that a binding happened, never the tenant
+     * id.
+     * @param tenantId Tenant UUID stored in `app.tenant_id`.
+     * @param options Only `local: true` (the default) is accepted; the binding is
+     * always transaction-local and is discarded on commit/rollback.
+     * @returns {Promise<void>} Resolves once the setting is bound transaction-locally.
+     * @throws {ValidationError} When the tenant id is invalid or a session-wide binding is requested.
+     */
+    setTenant(tenantId: string, options?: RlsBindingOptions, ...args: any[]): Promise<void>;
+    /**
+     * @description Clears the acting principal for the current transaction.
+     * @summary Resets `app.principal_id` to the empty string with
+     * `SELECT set_config($1, $2, true)`, so the clear is also transaction-local
+     * and never reaches the pooled session. A session-wide clear request fails
+     * with `ValidationError` before any SQL is sent.
+     * @param options Only `local: true` (the default) is accepted; the clear is
+     * always transaction-local and does not reach the pooled session.
+     * @returns {Promise<void>} Resolves once the setting is cleared transaction-locally.
+     * @throws {ValidationError} When a session-wide clear is requested.
+     */
+    clearPrincipal(options?: RlsBindingOptions, ...args: any[]): Promise<void>;
+    /**
+     * @description Returns the principal currently bound to the connection.
+     */
+    currentPrincipal(...args: any[]): Promise<string | null>;
+}
+/**
+ * @description Runs a callback inside a transaction with the RLS principal bound.
+ * @summary The executor must be a single connection (`pg.Client`), not a pool,
+ * because the transaction and the `app.principal_id` setting are
+ * connection-scoped. By default the transaction is rolled back, keeping
+ * integration-test mutations isolated; pass `{ commit: true }` for real writes.
+ */
+export declare function runAsPrincipal<T>(executor: RlsQueryExecutor, principalId: string, run: (executor: RlsQueryExecutor) => Promise<T>, options?: RunAsPrincipalOptions): Promise<T>;

package/lib/types/namespaces/rls/rls-bootstrap.service.d.mts

@@ -0,0 +1,157 @@
+/**
+ * @module integrations/namespaces/rls/bootstrap
+ * @summary Bootstrap service that applies the namespace row-level-security template.
+ * @description Wires the SQL template into a query executor (for example a
+ * `pg.Client`) so deployments apply the policies through application bootstrap
+ * or a migration runner instead of hand-running SQL. Also exposes helpers
+ * that bind `app.principal_id` transaction-locally for request-scoped access.
+ */
+import { ClientBasedService } from "@decaf-ts/core";
+import { InternalError } from "@decaf-ts/db-decorators";
+import type { RlsBootstrapConfig, RlsQueryExecutor, RunAsPrincipalOptions } from "./rls.types.d.mts";
+/**
+ * @description Thrown when the executor role cannot safely own the RLS helper functions.
+ * @summary Raised by
+ * `RlsBootstrapService.assertFunctionOwnerPrivileges()` when the current
+ * database role is neither `SUPERUSER` nor `BYPASSRLS` (or when its
+ * privileges cannot be determined). Extends
+ * `{@link InternalError}` so callers can catch it generically, while
+ * carrying the distinctive `RlsFunctionOwnerError` name for
+ * fail-closed matching.
+ * @class RlsFunctionOwnerError
+ * @category Namespaces
+ */
+export declare class RlsFunctionOwnerError extends InternalError {
+    constructor(message: string);
+}
+/**
+ * @description Options accepted by the transaction-local RLS binding helpers.
+ * @summary Session-wide binding is not supported: the only acceptable value is
+ * `local: true`, which is also the default. A `local: false` request is
+ * rejected with `ValidationError` before any SQL is sent, because a
+ * session-wide setting on a pooled connection leaks across requests.
+ * @interface RlsBindingOptions
+ * @property {true} [local] - Must be `true` or omitted (the default is `true`);
+ * any other value is rejected before any SQL is sent.
+ */
+export interface RlsBindingOptions {
+    local?: true;
+}
+/**
+ * @description Validates a principal identifier before binding it to the
+ * `app.principal_id` RLS setting.
+ * @summary Fail-closed shape guard shared by the binding helpers: the value
+ * must be a non-empty UUID string. On failure it throws a `ValidationError`
+ * with a fixed message that never echoes the rejected value, so invalid input
+ * cannot leak into error surfaces or logs.
+ * @function assertPrincipalId
+ * @param {string} principalId - Candidate principal (or tenant) UUID to validate.
+ * @returns {void}
+ * @throws {ValidationError} When the value is empty or not UUID-shaped; the message does not include the rejected value.
+ */
+export declare function assertPrincipalId(principalId: string): void;
+/**
+ * @description Applies the namespace RLS template through a SQL executor.
+ * @summary The service boots with a SQL executor (`pg.Client`, `pg.Pool`, or a
+ * compatible wrapper) and applies the namespace row-level-security template:
+ * function plus policy DDL executed sequentially. It is the deployment-side
+ * entry point for the RLS template, meant to run during application bootstrap
+ * or a migration runner instead of hand-running SQL. The template is
+ * idempotent and may run on every deployment.
+ * @class RlsBootstrapService
+ * @category Namespaces
+ */
+export declare class RlsBootstrapService extends ClientBasedService<RlsQueryExecutor, RlsBootstrapConfig> {
+    constructor();
+    initialize(...args: any[]): Promise<{
+        config: RlsBootstrapConfig;
+        client: RlsQueryExecutor;
+    }>;
+    /**
+     * @description Applies the configured (or bundled) RLS statement list.
+     * @summary The service is booted with an executor (`pg.Client`, `pg.Pool`, or a
+     * compatible wrapper) and applies function plus policy DDL sequentially. The
+     * template is idempotent and may run on every deployment. Before any DDL is
+     * sent, `assertFunctionOwnerPrivileges()` verifies that the current
+     * executor role is `SUPERUSER` or `BYPASSRLS` and fails closed otherwise,
+     * so `SECURITY DEFINER` helper functions are never created with an owner
+     * that would recurse under `FORCE ROW LEVEL SECURITY`.
+     * @return {Promise<{applied: number}>} The number of statements executed.
+     * @throws {RlsFunctionOwnerError} When the executor role is neither `SUPERUSER` nor `BYPASSRLS`, or its privileges cannot be determined.
+     * @throws {InternalError} When the resolved statement list is empty.
+     */
+    apply(...args: any[]): Promise<{
+        applied: number;
+    }>;
+    /**
+     * @description Verifies that the current executor role can own the RLS helper functions.
+     * @summary Runs `RLS_FUNCTION_OWNER_QUERY` through the configured executor
+     * and reads the current role's `rolsuper`/`rolbypassrls` flags from
+     * `pg_roles`. Fails closed: when the row is missing or the flags are not
+     * booleans, it throws `RlsFunctionOwnerError` with the same
+     * fail-closed semantics as an explicit privilege failure. Called
+     * automatically by `apply()` before any DDL is executed.
+     * @param args - Optional trailing decaf `Context` arguments forwarded to the log context.
+     * @return Resolves when the current role is `SUPERUSER` or `BYPASSRLS`.
+     * @throws {RlsFunctionOwnerError} When the executor role is neither `SUPERUSER` nor `BYPASSRLS`, or when its privileges cannot be determined from `pg_roles`.
+     */
+    assertFunctionOwnerPrivileges(...args: any[]): Promise<void>;
+    /**
+     * @description Resolves the statement list for the active configuration.
+     */
+    statements(): string[];
+    /**
+     * @description Binds the acting principal for the current transaction.
+     * @summary Issues parameterized `SELECT set_config($1, $2, true)` after
+     * validation, so the binding lives only for the current transaction and is
+     * discarded on commit/rollback — safe on pooled connections. A session-wide
+     * binding request fails with `ValidationError` before any SQL is sent, and
+     * the verbose log records only that a binding happened, never the principal
+     * id.
+     * @param principalId Principal UUID stored in `app.principal_id`.
+     * @param options Only `local: true` (the default) is accepted; the binding is
+     * always transaction-local and is discarded on commit/rollback.
+     * @returns {Promise<void>} Resolves once the setting is bound transaction-locally.
+     * @throws {ValidationError} When the principal id is invalid or a session-wide binding is requested.
+     */
+    setPrincipal(principalId: string, options?: RlsBindingOptions, ...args: any[]): Promise<void>;
+    /**
+     * @description Binds the acting tenant for the current transaction.
+     * @summary Issues parameterized `SELECT set_config($1, $2, true)` after
+     * validation, so the binding lives only for the current transaction and is
+     * discarded on commit/rollback — safe on pooled connections. A session-wide
+     * binding request fails with `ValidationError` before any SQL is sent, and
+     * the verbose log records only that a binding happened, never the tenant
+     * id.
+     * @param tenantId Tenant UUID stored in `app.tenant_id`.
+     * @param options Only `local: true` (the default) is accepted; the binding is
+     * always transaction-local and is discarded on commit/rollback.
+     * @returns {Promise<void>} Resolves once the setting is bound transaction-locally.
+     * @throws {ValidationError} When the tenant id is invalid or a session-wide binding is requested.
+     */
+    setTenant(tenantId: string, options?: RlsBindingOptions, ...args: any[]): Promise<void>;
+    /**
+     * @description Clears the acting principal for the current transaction.
+     * @summary Resets `app.principal_id` to the empty string with
+     * `SELECT set_config($1, $2, true)`, so the clear is also transaction-local
+     * and never reaches the pooled session. A session-wide clear request fails
+     * with `ValidationError` before any SQL is sent.
+     * @param options Only `local: true` (the default) is accepted; the clear is
+     * always transaction-local and does not reach the pooled session.
+     * @returns {Promise<void>} Resolves once the setting is cleared transaction-locally.
+     * @throws {ValidationError} When a session-wide clear is requested.
+     */
+    clearPrincipal(options?: RlsBindingOptions, ...args: any[]): Promise<void>;
+    /**
+     * @description Returns the principal currently bound to the connection.
+     */
+    currentPrincipal(...args: any[]): Promise<string | null>;
+}
+/**
+ * @description Runs a callback inside a transaction with the RLS principal bound.
+ * @summary The executor must be a single connection (`pg.Client`), not a pool,
+ * because the transaction and the `app.principal_id` setting are
+ * connection-scoped. By default the transaction is rolled back, keeping
+ * integration-test mutations isolated; pass `{ commit: true }` for real writes.
+ */
+export declare function runAsPrincipal<T>(executor: RlsQueryExecutor, principalId: string, run: (executor: RlsQueryExecutor) => Promise<T>, options?: RunAsPrincipalOptions): Promise<T>;

package/lib/types/namespaces/rls/rls.constants.d.cts

@@ -0,0 +1,52 @@
+/**
+ * @module integrations/namespaces/rls/constants
+ * @summary Row-level-security constants for the namespace authorization schema.
+ * @description Canonical permission keys, session settings, default role keys, and
+ * the tables covered by the namespace RLS template.
+ */
+/**
+ * @description Permission keys consumed by the SQL RLS policies.
+ * @summary A namespace reader can only read, a writer can also create/update/delete
+ * non-administrative rows, and an admin can do everything in the namespace.
+ */
+export declare const RLS_PERMISSION_KEYS: {
+    readonly Read: "namespace.read";
+    readonly Write: "namespace.write";
+    readonly Admin: "namespace.admin";
+};
+/**
+ * @description Session settings read by the RLS policies.
+ * @summary The application must set `app.principal_id` for every request-scoped
+ * database session or transaction before querying namespace tables.
+ */
+export declare const RLS_SETTINGS: {
+    readonly Principal: "app.principal_id";
+    readonly Tenant: "app.tenant_id";
+};
+/**
+ * @description Default role keys for the reader/writer/admin matrix.
+ * @summary Bootstrapping a tenant with these keys gives consumers a stable
+ * three-tier namespace role model without coupling them to custom role names.
+ */
+export declare const RLS_ROLE_KEYS: {
+    readonly Reader: "namespace-reader";
+    readonly Writer: "namespace-writer";
+    readonly Admin: "namespace-admin";
+};
+/**
+ * @description Boot-time privilege probe for the RLS `SECURITY DEFINER` helper functions.
+ * @summary Reads the current role's `rolsuper` and `rolbypassrls` flags from
+ * `pg_roles`. `RlsBootstrapService.assertFunctionOwnerPrivileges()` executes
+ * this query before applying any RLS DDL and refuses to proceed unless the
+ * executor role is `SUPERUSER` or `BYPASSRLS`, because a `SECURITY DEFINER`
+ * owner that does not bypass RLS makes every policy evaluation recurse under
+ * `FORCE ROW LEVEL SECURITY`.
+ */
+export declare const RLS_FUNCTION_OWNER_QUERY = "SELECT current_user AS rolname, rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user";
+/**
+ * @description Tables protected by the namespace RLS template.
+ * @summary Includes the authorization machinery, org profiles, protected
+ * resources, and the slice-1 credential/secret records.
+ */
+export declare const RLS_PROTECTED_TABLES: readonly ["tenants", "org_units", "org_unit_closure", "users", "groups", "principals", "tenant_memberships", "org_unit_memberships", "group_memberships", "permissions", "roles", "role_permissions", "role_assignments", "inheritance_blocks", "protected_resources", "resource_grants", "effective_permissions", "storage_bindings", "tenant_profiles", "org_unit_profiles", "credentials", "secrets"];
+export type RlsProtectedTable = (typeof RLS_PROTECTED_TABLES)[number];

package/lib/types/namespaces/rls/rls.constants.d.mts

@@ -0,0 +1,52 @@
+/**
+ * @module integrations/namespaces/rls/constants
+ * @summary Row-level-security constants for the namespace authorization schema.
+ * @description Canonical permission keys, session settings, default role keys, and
+ * the tables covered by the namespace RLS template.
+ */
+/**
+ * @description Permission keys consumed by the SQL RLS policies.
+ * @summary A namespace reader can only read, a writer can also create/update/delete
+ * non-administrative rows, and an admin can do everything in the namespace.
+ */
+export declare const RLS_PERMISSION_KEYS: {
+    readonly Read: "namespace.read";
+    readonly Write: "namespace.write";
+    readonly Admin: "namespace.admin";
+};
+/**
+ * @description Session settings read by the RLS policies.
+ * @summary The application must set `app.principal_id` for every request-scoped
+ * database session or transaction before querying namespace tables.
+ */
+export declare const RLS_SETTINGS: {
+    readonly Principal: "app.principal_id";
+    readonly Tenant: "app.tenant_id";
+};
+/**
+ * @description Default role keys for the reader/writer/admin matrix.
+ * @summary Bootstrapping a tenant with these keys gives consumers a stable
+ * three-tier namespace role model without coupling them to custom role names.
+ */
+export declare const RLS_ROLE_KEYS: {
+    readonly Reader: "namespace-reader";
+    readonly Writer: "namespace-writer";
+    readonly Admin: "namespace-admin";
+};
+/**
+ * @description Boot-time privilege probe for the RLS `SECURITY DEFINER` helper functions.
+ * @summary Reads the current role's `rolsuper` and `rolbypassrls` flags from
+ * `pg_roles`. `RlsBootstrapService.assertFunctionOwnerPrivileges()` executes
+ * this query before applying any RLS DDL and refuses to proceed unless the
+ * executor role is `SUPERUSER` or `BYPASSRLS`, because a `SECURITY DEFINER`
+ * owner that does not bypass RLS makes every policy evaluation recurse under
+ * `FORCE ROW LEVEL SECURITY`.
+ */
+export declare const RLS_FUNCTION_OWNER_QUERY = "SELECT current_user AS rolname, rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user";
+/**
+ * @description Tables protected by the namespace RLS template.
+ * @summary Includes the authorization machinery, org profiles, protected
+ * resources, and the slice-1 credential/secret records.
+ */
+export declare const RLS_PROTECTED_TABLES: readonly ["tenants", "org_units", "org_unit_closure", "users", "groups", "principals", "tenant_memberships", "org_unit_memberships", "group_memberships", "permissions", "roles", "role_permissions", "role_assignments", "inheritance_blocks", "protected_resources", "resource_grants", "effective_permissions", "storage_bindings", "tenant_profiles", "org_unit_profiles", "credentials", "secrets"];
+export type RlsProtectedTable = (typeof RLS_PROTECTED_TABLES)[number];

package/lib/types/namespaces/rls/rls.template.d.cts

@@ -0,0 +1,42 @@
+import type { RlsPolicySet } from "./rls.types.d.cts";
+/**
+ * @description Helper functions backing the namespace RLS policies.
+ * @summary Each function is idempotently created with `CREATE OR REPLACE`.
+ * `app_rls_principal_for_subject(text, uuid)` is additionally `SECURITY
+ * DEFINER` with `search_path` pinned to `public, pg_temp` and `REVOKE`d from
+ * `PUBLIC`: it maps an authenticated subject (and optional tenant) to the
+ * single matching principal UUID - or `NULL` when the match is ambiguous or
+ * absent - and is consumed by privileged resolvers such as
+ * `resolvePrincipalForSubject` from `./principal-resolver`.
+ */
+export declare const RLS_FUNCTION_STATEMENTS: readonly string[];
+/**
+ * @description Canonical reader/writer/admin policy matrix.
+ * @summary Administrative tables (permissions, roles, role assignments,
+ * inheritance blocks, storage bindings) are visible only to admins. Content
+ * tables are visible to readers and writable by writers. Users always see their
+ * own identity rows and their own credentials/secrets.
+ */
+export declare const NAMESPACE_RLS_POLICY_SETS: readonly RlsPolicySet[];
+/**
+ * @description Generates enable/force and policy DDL for a policy set.
+ * @summary `DROP POLICY IF EXISTS` makes the output safe to replay on every
+ * deployment. Missing command expressions leave that command denied.
+ */
+export declare function rlsPolicyStatements(policySets?: readonly RlsPolicySet[]): string[];
+/**
+ * @description Full namespace RLS bootstrap statement list.
+ * @summary Helper functions followed by enable/force and policy DDL for every
+ * table in {@link RLS_PROTECTED_TABLES}. Apply after the namespace schema
+ * exists and before request-scoped traffic reaches the database.
+ */
+export declare function rlsBootstrapStatements(): string[];
+/**
+ * @description Tables targeted by the bundled namespace template.
+ */
+export declare function rlsPolicyTables(policySets?: readonly RlsPolicySet[]): string[];
+/**
+ * @description Asserts that the bundled policy template covers every protected
+ * table. Exposed for deployment checks and unit tests.
+ */
+export declare function assertRlsTableCoverage(policySets?: readonly RlsPolicySet[]): void;

package/lib/types/namespaces/rls/rls.template.d.mts

@@ -0,0 +1,42 @@
+import type { RlsPolicySet } from "./rls.types.d.mts";
+/**
+ * @description Helper functions backing the namespace RLS policies.
+ * @summary Each function is idempotently created with `CREATE OR REPLACE`.
+ * `app_rls_principal_for_subject(text, uuid)` is additionally `SECURITY
+ * DEFINER` with `search_path` pinned to `public, pg_temp` and `REVOKE`d from
+ * `PUBLIC`: it maps an authenticated subject (and optional tenant) to the
+ * single matching principal UUID - or `NULL` when the match is ambiguous or
+ * absent - and is consumed by privileged resolvers such as
+ * `resolvePrincipalForSubject` from `./principal-resolver`.
+ */
+export declare const RLS_FUNCTION_STATEMENTS: readonly string[];
+/**
+ * @description Canonical reader/writer/admin policy matrix.
+ * @summary Administrative tables (permissions, roles, role assignments,
+ * inheritance blocks, storage bindings) are visible only to admins. Content
+ * tables are visible to readers and writable by writers. Users always see their
+ * own identity rows and their own credentials/secrets.
+ */
+export declare const NAMESPACE_RLS_POLICY_SETS: readonly RlsPolicySet[];
+/**
+ * @description Generates enable/force and policy DDL for a policy set.
+ * @summary `DROP POLICY IF EXISTS` makes the output safe to replay on every
+ * deployment. Missing command expressions leave that command denied.
+ */
+export declare function rlsPolicyStatements(policySets?: readonly RlsPolicySet[]): string[];
+/**
+ * @description Full namespace RLS bootstrap statement list.
+ * @summary Helper functions followed by enable/force and policy DDL for every
+ * table in {@link RLS_PROTECTED_TABLES}. Apply after the namespace schema
+ * exists and before request-scoped traffic reaches the database.
+ */
+export declare function rlsBootstrapStatements(): string[];
+/**
+ * @description Tables targeted by the bundled namespace template.
+ */
+export declare function rlsPolicyTables(policySets?: readonly RlsPolicySet[]): string[];
+/**
+ * @description Asserts that the bundled policy template covers every protected
+ * table. Exposed for deployment checks and unit tests.
+ */
+export declare function assertRlsTableCoverage(policySets?: readonly RlsPolicySet[]): void;

package/lib/types/namespaces/rls/rls.types.d.cts

@@ -0,0 +1,77 @@
+/**
+ * @module integrations/namespaces/rls/types
+ * @summary Types shared by the namespace row-level-security template and services.
+ * @description Defines the minimal query-executor contract (compatible with
+ * `pg.Client`/`pg.Pool`), the policy descriptor used to generate DDL, and the
+ * bootstrap/session configuration shapes.
+ */
+/**
+ * @description Minimal asynchronous SQL executor required by the RLS services.
+ * @summary Matches the shape of `pg.Client.query()` without importing `pg` at
+ * runtime. Consumers can pass a `pg.Client`, a `pg.Pool`, or any compatible
+ * wrapper (including test doubles).
+ */
+export interface RlsQueryExecutor {
+    query(sql: string, values?: unknown[]): Promise<{
+        rowCount?: number | null;
+        rows?: unknown[];
+    }>;
+}
+/**
+ * @description A set of row-level-security policies for one table.
+ * @summary Each expression is a PostgreSQL boolean expression evaluated against
+ * the row. `insert` uses `WITH CHECK`; `update` uses `USING` and `WITH CHECK`.
+ */
+export interface RlsPolicySet {
+    /**
+     * @description Table name (optionally schema-qualified) to protect.
+     */
+    table: string;
+    /**
+     * @description `USING` expression for `SELECT`; omit to leave `SELECT` denied.
+     */
+    select?: string;
+    /**
+     * @description `WITH CHECK` expression for `INSERT`; omit to deny inserts.
+     */
+    insert?: string;
+    /**
+     * @description `USING`/`WITH CHECK` expression for `UPDATE`; omit to deny updates.
+     */
+    update?: string;
+    /**
+     * @description `USING` expression for `DELETE`; omit to deny deletes.
+     */
+    delete?: string;
+    /**
+     * @description Whether to also emit `ENABLE`/`FORCE ROW LEVEL SECURITY`.
+     * @default true
+     */
+    enable?: boolean;
+}
+/**
+ * @description Configuration accepted by {@link RlsBootstrapService}.
+ */
+export interface RlsBootstrapConfig {
+    /**
+     * @description Statements to apply instead of the bundled namespace template.
+     * @summary Useful for targeted tests or partial deployments. Statements are
+     * executed sequentially and must be idempotent when applied repeatedly.
+     */
+    statements?: string[];
+    /**
+     * @description Policy sets to generate instead of the bundled namespace policy
+     * template. Function helpers are still emitted unless `statements` is supplied.
+     */
+    policies?: RlsPolicySet[];
+}
+/**
+ * @description Options for {@link runAsPrincipal}.
+ */
+export interface RunAsPrincipalOptions {
+    /**
+     * @description Commit the transaction when the callback succeeds.
+     * @default false — the transaction is rolled back to keep tests isolated.
+     */
+    commit?: boolean;
+}