@smplcty/auth 8.0.0 → 9.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -1
- package/package.json +2 -2
- package/schema/functions/auth_all_tenants.yaml +30 -0
- package/schema/functions/auth_can_admin_user.yaml +2 -0
- package/schema/functions/auth_create_user.yaml +2 -0
- package/schema/functions/auth_has_role.yaml +2 -0
- package/schema/functions/auth_in_tenant.yaml +2 -0
- package/schema/functions/auth_tenant_ids.yaml +39 -0
- package/schema/functions/resolve_session.yaml +2 -0
- package/schema/tables/tenants.yaml +8 -1
package/README.md
CHANGED
|
@@ -499,7 +499,7 @@ The library ships its schema as schema-flow YAML inside the package at `@smplcty
|
|
|
499
499
|
|
|
500
500
|
### Consuming with [`@smplcty/schema-flow`](https://www.npmjs.com/package/@smplcty/schema-flow)
|
|
501
501
|
|
|
502
|
-
Requires **`@smplcty/schema-flow >= 0.
|
|
502
|
+
Requires **`@smplcty/schema-flow >= 0.18.2`** — the shipped seeds assign no primary keys (the app-init user and the standard roles are matched by their natural keys, `name`/`kind`) and rely on insert-only seeding, where an existing row is never overwritten. `0.13.0` makes insert-only the default (the old per-table `seeds_on_conflict` knob is gone); on older versions these seeds would upsert and clobber any consumer edits to the standard roles on every migration. `0.14.0` is required so `resolve_session` converges: it canonicalises function type aliases (`resolve_session` returns a `TABLE(… expires_at timestamptz …)`), so the function no longer reports phantom drift on every `plan`/`run`/`drift`. `0.18.2` is required for the `SECURITY DEFINER` search_path pins (see below): it emits the pin as a valid `SET search_path` clause and compares it against `pg_proc.proconfig` semantically (whitespace/case-normalised), so a pinned function converges to a clean no-op instead of reporting phantom drift.
|
|
503
503
|
|
|
504
504
|
If you are upgrading an existing database, run schema-flow with `--allow-destructive` once: `0.14.0` recreates a function whose return type changed via `DROP … CASCADE` + a post-apply convergence pass that restores the dependent RLS policies, and (where a live DB carries a plain `UNIQUE` constraint sharing a name with one of auth's partial-unique indexes) drops the constraint and builds the partial index. Both paths are gated behind the flag; without it the change is reported as blocked rather than silently no-applied.
|
|
505
505
|
|
|
@@ -514,6 +514,14 @@ default:
|
|
|
514
514
|
|
|
515
515
|
The `audit` mixin makes `created_by`/`updated_by` NOT NULL, stamped from `app.actor_id`. Rows seeded during migration have no request actor, so the shipped `post/` script back-fills them to the seeded `app-init` service user (resolved by name, not a fixed id) before the NOT NULL tighten phase — see the config for details.
|
|
516
516
|
|
|
517
|
+
### ⚠️ Known limitation — auth must deploy into the `public` schema
|
|
518
|
+
|
|
519
|
+
The library's seven `SECURITY DEFINER` functions (`auth_has_role`, `auth_can_admin_user`, `auth_in_tenant`, `auth_all_tenants`, `auth_tenant_ids`, `resolve_session`, `auth_create_user`) each ship with a **pinned `search_path` of `pg_catalog, public`**. This is a security hardening: a `SECURITY DEFINER` function otherwise inherits the _caller's_ `search_path`, so a caller who plants a shadow object (a fake `user_roles` table, a fake `current_user_id()`) in an earlier-resolving schema could make an unqualified name inside these functions resolve to _their_ object — and it would run with the definer's elevated rights, subverting an authorization check. Pinning to the trusted schema list closes that. (`current_user_id()` is `SECURITY INVOKER`, so it carries no escalation risk and is intentionally left unpinned.)
|
|
520
|
+
|
|
521
|
+
The consequence: **`public` is hardcoded into the shipped pin**, so auth must be deployed into the `public` schema. Every consumer today deploys there (schema-flow's default), so this is a no-op for you in practice — but if you deploy auth into a non-`public` schema (e.g. `auth`, `app`), the pinned path won't contain auth's tables and the functions will break. schema-flow does not yet interpolate the deploy `pgSchema` into `set:` values, which is the only reason the pin can't be schema-agnostic.
|
|
522
|
+
|
|
523
|
+
If you have a concrete, justifiable need to deploy auth into a non-`public` schema, open an issue — the fix is a schema-flow enhancement to interpolate the deploy schema into `set.search_path`, after which the pin drops the hardcoded `public` and portability is restored.
|
|
524
|
+
|
|
517
525
|
### Soft delete
|
|
518
526
|
|
|
519
527
|
Every table carries the `soft_delete` mixin (`deleted_at`). The library **honors** it — `resolve_session`, `validateSession`, `findUserByCommunicationMethod`, `getUserRoleNames`, and the flat-tenant preset all exclude soft-deleted rows — so a soft-deleted session, user, communication method, or role assignment stops taking effect immediately. Unique indexes are partial (`WHERE deleted_at IS NULL`) so a name/code can be reused after its row is archived. Setting/clearing `deleted_at` is a plain write your app owns; the library ships no delete setter. (Note: writing `deleted_at` on an _audited_ table goes through the audit trigger, so set `app.actor_id` first — e.g. inside `withSession`/`withServiceContext`.)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@smplcty/auth",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "9.0.0",
|
|
4
4
|
"description": "Robust, type-safe session and role-based authentication primitives for PostgreSQL apps using Row-Level Security.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -105,7 +105,7 @@
|
|
|
105
105
|
"devDependencies": {
|
|
106
106
|
"@eslint/js": "^10.0.1",
|
|
107
107
|
"@release-it/keep-a-changelog": "^7.1.0",
|
|
108
|
-
"@smplcty/schema-flow": "^0.
|
|
108
|
+
"@smplcty/schema-flow": "^0.18.2",
|
|
109
109
|
"@smplcty/twilio": "^0.1.1",
|
|
110
110
|
"@testcontainers/postgresql": "^12.0.2",
|
|
111
111
|
"@types/node": "^25.9.3",
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
name: auth_all_tenants
|
|
2
|
+
language: plpgsql
|
|
3
|
+
volatility: stable
|
|
4
|
+
security: definer
|
|
5
|
+
set:
|
|
6
|
+
search_path: pg_catalog, public
|
|
7
|
+
# True when the current actor holds any live wildcard role — a user_roles row
|
|
8
|
+
# with tenant_id IS NULL, which reaches every tenant (surfaced elsewhere as the
|
|
9
|
+
# app.all_tenants GUC). The all-access companion to auth_tenant_ids: a wildcard
|
|
10
|
+
# grant can't be enumerated into a finite id set, so scope tests OR this against
|
|
11
|
+
# `tenant_id IN (SELECT auth_tenant_ids())`. False when there is no actor.
|
|
12
|
+
#
|
|
13
|
+
# Wrap the call in a subquery — `(SELECT auth_all_tenants())` — in a policy so
|
|
14
|
+
# the planner evaluates it as an InitPlan ONCE per query instead of per row.
|
|
15
|
+
returns: boolean
|
|
16
|
+
args: []
|
|
17
|
+
body: |
|
|
18
|
+
BEGIN
|
|
19
|
+
RETURN EXISTS (
|
|
20
|
+
SELECT 1
|
|
21
|
+
FROM user_roles ur
|
|
22
|
+
WHERE ur.user_id = current_user_id()
|
|
23
|
+
AND ur.deleted_at IS NULL
|
|
24
|
+
AND ur.tenant_id IS NULL
|
|
25
|
+
);
|
|
26
|
+
END;
|
|
27
|
+
comment: >
|
|
28
|
+
True if the current actor holds any live wildcard (all-tenants) role. The
|
|
29
|
+
all-access companion to auth_tenant_ids. SECURITY DEFINER so RLS policies can
|
|
30
|
+
use it without recursing on user_roles.
|
|
@@ -2,6 +2,8 @@ name: auth_can_admin_user
|
|
|
2
2
|
language: plpgsql
|
|
3
3
|
volatility: stable
|
|
4
4
|
security: definer
|
|
5
|
+
set:
|
|
6
|
+
search_path: pg_catalog, public
|
|
5
7
|
# True when the current actor is a security admin for at least one tenant the
|
|
6
8
|
# target user holds a role in — i.e. they share a tenant where the actor holds
|
|
7
9
|
# `security`. This is the "a security admin manages the users in their tenants"
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
name: auth_create_user
|
|
2
2
|
language: plpgsql
|
|
3
3
|
security: definer
|
|
4
|
+
set:
|
|
5
|
+
search_path: pg_catalog, public
|
|
4
6
|
# The authority-checked, atomic way for an app_rls request (a security admin) to
|
|
5
7
|
# provision a human user. Raw INSERT on `users` is closed under RLS — a user
|
|
6
8
|
# must never exist without the roles and contact methods that make it usable,
|
|
@@ -2,6 +2,8 @@ name: auth_has_role
|
|
|
2
2
|
language: plpgsql
|
|
3
3
|
volatility: stable
|
|
4
4
|
security: definer
|
|
5
|
+
set:
|
|
6
|
+
search_path: pg_catalog, public
|
|
5
7
|
# True when the current request actor holds `role_name` with authority over
|
|
6
8
|
# `target_tenant_id`. A wildcard assignment (user_roles.tenant_id IS NULL)
|
|
7
9
|
# reaches every tenant, so it always qualifies. Passing a NULL target means
|
|
@@ -2,6 +2,8 @@ name: auth_in_tenant
|
|
|
2
2
|
language: plpgsql
|
|
3
3
|
volatility: stable
|
|
4
4
|
security: definer
|
|
5
|
+
set:
|
|
6
|
+
search_path: pg_catalog, public
|
|
5
7
|
# True when the current actor holds ANY role reaching `target_tenant_id`
|
|
6
8
|
# (directly or via a wildcard assignment). Used where visibility is granted to
|
|
7
9
|
# every member of a tenant regardless of which role they hold — e.g. a tenant
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
name: auth_tenant_ids
|
|
2
|
+
language: plpgsql
|
|
3
|
+
volatility: stable
|
|
4
|
+
security: definer
|
|
5
|
+
set:
|
|
6
|
+
search_path: pg_catalog, public
|
|
7
|
+
# The set of tenant ids the current actor holds a live, tenant-scoped role in
|
|
8
|
+
# (wildcard grants — user_roles.tenant_id IS NULL — are NOT in this set; test
|
|
9
|
+
# them with auth_all_tenants()). Returns nothing when there is no actor.
|
|
10
|
+
#
|
|
11
|
+
# This is the set-based, planner-friendly counterpart to auth_in_tenant. Used in
|
|
12
|
+
# an *uncorrelated* subquery an RLS policy resolves ONCE per query rather than
|
|
13
|
+
# once per row:
|
|
14
|
+
#
|
|
15
|
+
# USING (
|
|
16
|
+
# (SELECT auth_all_tenants()) -- InitPlan, evaluated once
|
|
17
|
+
# OR tenant_id IN (SELECT auth_tenant_ids()) -- hashed SubPlan, materialized once
|
|
18
|
+
# )
|
|
19
|
+
#
|
|
20
|
+
# Because the membership set is independent of the scanned row, the planner
|
|
21
|
+
# folds it into a hashed SubPlan and probes it per row instead of re-running a
|
|
22
|
+
# SECURITY DEFINER function per row (auth_in_tenant's cost on large scans). Keep
|
|
23
|
+
# auth_in_tenant for scalar/one-off call sites; reach for this on hot scan paths.
|
|
24
|
+
returns: SETOF bigint
|
|
25
|
+
args: []
|
|
26
|
+
body: |
|
|
27
|
+
BEGIN
|
|
28
|
+
RETURN QUERY
|
|
29
|
+
SELECT ur.tenant_id
|
|
30
|
+
FROM user_roles ur
|
|
31
|
+
WHERE ur.user_id = current_user_id()
|
|
32
|
+
AND ur.deleted_at IS NULL
|
|
33
|
+
AND ur.tenant_id IS NOT NULL;
|
|
34
|
+
END;
|
|
35
|
+
comment: >
|
|
36
|
+
The set of tenant ids the current actor holds a live, tenant-scoped role in
|
|
37
|
+
(wildcard grants excluded — see auth_all_tenants). SECURITY DEFINER so RLS
|
|
38
|
+
policies can use it in an uncorrelated subquery — resolved once per query, not
|
|
39
|
+
per row — without recursing on user_roles.
|
|
@@ -2,6 +2,8 @@ name: resolve_session
|
|
|
2
2
|
language: plpgsql
|
|
3
3
|
volatility: stable
|
|
4
4
|
security: definer
|
|
5
|
+
set:
|
|
6
|
+
search_path: pg_catalog, public
|
|
5
7
|
# A PURE resolver. Given a session token hash, it returns the session's
|
|
6
8
|
# user, its expiry, the user's selectable roles (split from privileges by
|
|
7
9
|
# roles.is_privilege), and the user's privileges. It takes NO role
|
|
@@ -54,7 +54,14 @@ policies:
|
|
|
54
54
|
for: SELECT
|
|
55
55
|
to: app_rls
|
|
56
56
|
permissive: true
|
|
57
|
-
|
|
57
|
+
# Decorrelated scope test: the actor's reachable tenants are resolved once
|
|
58
|
+
# per query (InitPlan + hashed SubPlan) rather than once per row, so this
|
|
59
|
+
# scales on large scans. Equivalent to auth_in_tenant(tenants.tenant_id) —
|
|
60
|
+
# which stays for scalar call sites — but planner-friendly. See
|
|
61
|
+
# auth_tenant_ids / auth_all_tenants.
|
|
62
|
+
using: |-
|
|
63
|
+
(SELECT auth_all_tenants())
|
|
64
|
+
OR tenants.tenant_id IN (SELECT auth_tenant_ids())
|
|
58
65
|
- name: tenants_insert
|
|
59
66
|
for: INSERT
|
|
60
67
|
to: app_rls
|