@wtfalch/authz-store 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Tallis Falch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @wtfalch/authz-store
+
+`@wtfalch/authz` decides. This stores.
+
+Both applications on the engine wrote their own persistence and lifecycle layer
+— the schema, the audit writer, the tenant and team trees, invitations,
+credentials, break-glass, the boot checks — and arrived at the same one. Of the
+13,107 shared lines, 106 differ, and three quarters of those are one application
+lagging the other or a stale comment. This package is where that code goes so it
+exists once.
+
+`/Users/william.falch/Documents/dev/authz/docs/shared-persistence-map.md` is the
+map: what moves here, what stays per-application, and why this is a second
+package rather than a subpath on the engine.
+
+## Status
+
+**Unadopted, unpublished, private.** Moved so far: credential secrets, the
+`ScopedDb` seam, every table definition, and `ownerCoverage`, the first module
+that reads rows. Neither application depends on this yet.
+
+New here, not moved: `authz_grants`, grants stored per person rather than
+compiled from a role, and `guestGrants`, which reads a tenant's guest grants
+with each one's status (`current`, `lapsed` or `revoked`). A guest row must
+have `expires_at`. Chat reads this to act on expiry; see
+https://github.com/wtfalch/authz/issues/42.
+
+Tests run against a real Postgres — PGlite, compiled to wasm and started in the
+test process — so no container, service or network is needed. Most tests build
+the tables from the drizzle definitions. `src/migrate.test.ts` applies the
+shipped SQL instead and fails when the two disagree on a column, a type,
+nullability or an index name.
+
+## Migrations
+
+The package ships its own SQL in `migrations/`, and `migrateStore(db)` applies
+it. Run it before the app's own migrations, so every table the package owns
+exists before an app migration references it. Each file runs once, in one
+transaction, and is recorded in `authz_store_migrations`. Never edit a shipped
+file; a change is a new numbered one.
+
+`0001_baseline.sql` is every store table as manage's live schema had it on
+2026-09-22. Three things stay with each app, because each lists something the
+app owns:
+
+- `tenants_ceiling_offered_check` and `tenants_self_denied_offered_check`, which
+  list that app's offered permissions.
+- The foreign key from `break_glass_sessions.operator_id` to `profiles`.
+
+The baseline is for a new database. manage and otf `web/` already have these
+tables, so each needs a one-off reconciliation: bring the schema to the
+baseline, then insert `0001_baseline.sql` into `authz_store_migrations` by
+hand. otf also lacks `authz_roles.updated_by` and the `'activation'`
+assignment source.
+
+What a host must supply is growing, and it is all explicit: a module that needs
+the host's `APPLICATION_ID` and `PLATFORM_ID` takes them as a `PolicyBinding`
+argument rather than importing them, because the two applications differ there.
+
+The remaining ~12,800 lines, and the one-off migration each application needs to
+adopt them, are not started.
+
+## Why it is not part of `@wtfalch/authz`
+
+The engine has no runtime dependencies, and a test scans its whole published
+`dist` for anything Node-only — a `node:` import, `require(`, `process.`,
+`Buffer` — then runs it inside a real workerd process. This package's first file
+imports `node:crypto`, which is precisely what that scan rejects. The separation
+is asserted, not intended: see `the store package exports exactly what it
+promises, and is Node-only by nature` in
+`/Users/william.falch/Documents/dev/authz/scripts/tests/package-contract.test.mjs`.
+
+## A note for a Next.js host
+
+Both applications guard this code with Next's `server-only` marker. A
+framework-neutral package cannot import it, so that import is dropped here. A
+host that wants the guard re-exports these functions through its own
+`server-only` module. `generateCredentialSecret` reaching a client bundle is the
+thing worth preventing.

package/dist/credential-secret.d.ts

@@ -0,0 +1,70 @@
+/**
+ * What a credential's secret is, and the three things every side of the
+ * bearer path has to agree on: how one is generated, how it is stored, and
+ * how a presented string is turned back into something a query can look up
+ * (D7, D20).
+ *
+ * Kept in its own file rather than beside either half, because the minting
+ * side (`credentials.ts`) and the authenticating side (`bearer.ts`) are
+ * written against each other and a second copy of these rules in one of them
+ * is how the two stop matching. Nothing here touches the database.
+ *
+ * **The shape: `<PREFIX>_<random>`.** The leading marker is the reason a
+ * secret is findable at all once it has leaked: it makes a credential
+ * greppable in a log, a repository scan or a paste, which is what lets it be
+ * revoked before anyone has to work out whose it was. That is the same
+ * reasoning behind every provider's token prefix, and it costs nothing.
+ *
+ * **This module is server-side only.** Both hosts guard that with Next's
+ * `server-only` marker, which a framework-neutral package cannot import. A host
+ * that needs the guard re-exports these through its own `server-only` module;
+ * `generateCredentialSecret` in a client bundle is the thing to prevent.
+ *
+ * **Stored hashed, shown once**, exactly as an invitation token is (D10).
+ * The row keeps `sha256(secret)` and a short display prefix; the secret
+ * itself exists only in the response to the mint that created it. A plain
+ * sha256 rather than a password hash is correct here and would not be for a
+ * password: this is 32 bytes of `randomBytes`, not something a person chose,
+ * so there is no dictionary to run and no work factor worth paying on every
+ * request the credential makes.
+ */
+/** The marker every secret this app mints begins with. */
+export declare const CREDENTIAL_PREFIX = "wtfk";
+/** Bytes of randomness behind the marker. The same 32 the invitation token uses. */
+export declare const CREDENTIAL_SECRET_BYTES = 32;
+/**
+ * How much of the random half is kept in clear for display. Eight hex
+ * characters is four bytes: enough to tell a tenant's credentials apart on a
+ * page, and 2^-224 of what an attacker would still need to guess.
+ */
+export declare const CREDENTIAL_PREFIX_LENGTH = 8;
+/** A minted secret, and the two things the row stores about it. */
+export interface GeneratedCredentialSecret {
+    /** Returned to the minter once and never stored or logged in clear. */
+    readonly secret: string;
+    readonly secretHash: string;
+    readonly secretPrefix: string;
+}
+export declare function generateCredentialSecret(): GeneratedCredentialSecret;
+/** The stored form. The whole secret is hashed, marker included, so a lookup can never match on the marker alone. */
+export declare function hashCredentialSecret(secret: string): string;
+/**
+ * Whether a presented string could be one of this app's secrets at all,
+ * checked before it is hashed or sent anywhere.
+ *
+ * This is a cheap filter, not a security boundary: the hash lookup is what
+ * decides. It exists so that an `Authorization: Bearer <a session cookie>`,
+ * or a token belonging to some other system, is refused without a database
+ * round trip, and so that nothing unbounded reaches `createHash`.
+ */
+export declare function looksLikeCredentialSecret(presented: string): boolean;
+/**
+ * The secret carried by an `Authorization` header, or null.
+ *
+ * Only the `Bearer` scheme, and only one space, because being generous about
+ * the framing of a credential is how one ends up matching something that was
+ * never meant to be one. A header this does not recognise is not an error to
+ * report: it is a request with no credential, which the caller treats the
+ * same as a request that sent none.
+ */
+export declare function bearerFromHeader(header: string | null | undefined): string | null;

package/dist/credential-secret.js

@@ -0,0 +1,89 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * What a credential's secret is, and the three things every side of the
+ * bearer path has to agree on: how one is generated, how it is stored, and
+ * how a presented string is turned back into something a query can look up
+ * (D7, D20).
+ *
+ * Kept in its own file rather than beside either half, because the minting
+ * side (`credentials.ts`) and the authenticating side (`bearer.ts`) are
+ * written against each other and a second copy of these rules in one of them
+ * is how the two stop matching. Nothing here touches the database.
+ *
+ * **The shape: `<PREFIX>_<random>`.** The leading marker is the reason a
+ * secret is findable at all once it has leaked: it makes a credential
+ * greppable in a log, a repository scan or a paste, which is what lets it be
+ * revoked before anyone has to work out whose it was. That is the same
+ * reasoning behind every provider's token prefix, and it costs nothing.
+ *
+ * **This module is server-side only.** Both hosts guard that with Next's
+ * `server-only` marker, which a framework-neutral package cannot import. A host
+ * that needs the guard re-exports these through its own `server-only` module;
+ * `generateCredentialSecret` in a client bundle is the thing to prevent.
+ *
+ * **Stored hashed, shown once**, exactly as an invitation token is (D10).
+ * The row keeps `sha256(secret)` and a short display prefix; the secret
+ * itself exists only in the response to the mint that created it. A plain
+ * sha256 rather than a password hash is correct here and would not be for a
+ * password: this is 32 bytes of `randomBytes`, not something a person chose,
+ * so there is no dictionary to run and no work factor worth paying on every
+ * request the credential makes.
+ */
+/** The marker every secret this app mints begins with. */
+export const CREDENTIAL_PREFIX = 'wtfk';
+/** Bytes of randomness behind the marker. The same 32 the invitation token uses. */
+export const CREDENTIAL_SECRET_BYTES = 32;
+/**
+ * How much of the random half is kept in clear for display. Eight hex
+ * characters is four bytes: enough to tell a tenant's credentials apart on a
+ * page, and 2^-224 of what an attacker would still need to guess.
+ */
+export const CREDENTIAL_PREFIX_LENGTH = 8;
+export function generateCredentialSecret() {
+    const random = randomBytes(CREDENTIAL_SECRET_BYTES).toString('hex');
+    const secret = `${CREDENTIAL_PREFIX}_${random}`;
+    return {
+        secret,
+        secretHash: hashCredentialSecret(secret),
+        secretPrefix: random.slice(0, CREDENTIAL_PREFIX_LENGTH),
+    };
+}
+/** The stored form. The whole secret is hashed, marker included, so a lookup can never match on the marker alone. */
+export function hashCredentialSecret(secret) {
+    return createHash('sha256').update(secret).digest('hex');
+}
+/**
+ * Whether a presented string could be one of this app's secrets at all,
+ * checked before it is hashed or sent anywhere.
+ *
+ * This is a cheap filter, not a security boundary: the hash lookup is what
+ * decides. It exists so that an `Authorization: Bearer <a session cookie>`,
+ * or a token belonging to some other system, is refused without a database
+ * round trip, and so that nothing unbounded reaches `createHash`.
+ */
+export function looksLikeCredentialSecret(presented) {
+    const expected = `${CREDENTIAL_PREFIX}_`.length + CREDENTIAL_SECRET_BYTES * 2;
+    if (presented.length !== expected)
+        return false;
+    if (!presented.startsWith(`${CREDENTIAL_PREFIX}_`))
+        return false;
+    return /^[0-9a-f]+$/.test(presented.slice(`${CREDENTIAL_PREFIX}_`.length));
+}
+/**
+ * The secret carried by an `Authorization` header, or null.
+ *
+ * Only the `Bearer` scheme, and only one space, because being generous about
+ * the framing of a credential is how one ends up matching something that was
+ * never meant to be one. A header this does not recognise is not an error to
+ * report: it is a request with no credential, which the caller treats the
+ * same as a request that sent none.
+ */
+export function bearerFromHeader(header) {
+    if (!header)
+        return null;
+    const match = /^Bearer ([^\s]+)$/.exec(header);
+    if (!match?.[1])
+        return null;
+    const presented = match[1];
+    return looksLikeCredentialSecret(presented) ? presented : null;
+}

package/dist/grants.d.ts

@@ -0,0 +1,395 @@
+import type { ResourceGrant } from '@wtfalch/authz';
+import type { PolicyBinding } from './owners.js';
+import type { DbOrTx } from './scoped.js';
+/**
+ * Grants to one person, stored rather than compiled from a role. Guests live here: an invitation
+ * mints rows inside the catalogue's `guest` ceiling, and the engine refuses anything above it.
+ */
+export declare const policyGrants: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "authz_grants";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "authz_grants";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tenantId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tenant_id";
+            tableName: "authz_grants";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        applicationId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "application_id";
+            tableName: "authz_grants";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        platformId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "platform_id";
+            tableName: "authz_grants";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        permission: import("drizzle-orm/pg-core").PgColumn<{
+            name: "permission";
+            tableName: "authz_grants";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        principalId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "principal_id";
+            tableName: "authz_grants";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        principalClass: import("drizzle-orm/pg-core").PgColumn<{
+            name: "principal_class";
+            tableName: "authz_grants";
+            dataType: "string";
+            columnType: "PgText";
+            data: "human" | "api_key" | "agent" | "service";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: "human" | "api_key" | "agent" | "service";
+        }>;
+        boundary: import("drizzle-orm/pg-core").PgColumn<{
+            name: "boundary";
+            tableName: "authz_grants";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: {
+                kind: "organisation";
+                organisationId: string;
+            } | {
+                kind: "organisations";
+                organisationIds: string[];
+            } | {
+                kind: "platform";
+            };
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: {
+                kind: "organisation";
+                organisationId: string;
+            } | {
+                kind: "organisations";
+                organisationIds: string[];
+            } | {
+                kind: "platform";
+            };
+        }>;
+        scope: import("drizzle-orm/pg-core").PgColumn<{
+            name: "scope";
+            tableName: "authz_grants";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: {
+                kind: "organisation";
+            } | {
+                kind: "team";
+                teamId: string;
+                descendants: boolean;
+            } | {
+                kind: "own_teams";
+                descendants: boolean;
+            } | {
+                kind: "resource";
+                resourceType: string;
+                resourceId: string;
+            };
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: {
+                kind: "organisation";
+            } | {
+                kind: "team";
+                teamId: string;
+                descendants: boolean;
+            } | {
+                kind: "own_teams";
+                descendants: boolean;
+            } | {
+                kind: "resource";
+                resourceType: string;
+                resourceId: string;
+            };
+        }>;
+        constraints: import("drizzle-orm/pg-core").PgColumn<{
+            name: "constraints";
+            tableName: "authz_grants";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: ({
+                kind: "organisation";
+            } | {
+                kind: "team";
+                teamId: string;
+                descendants: boolean;
+            } | {
+                kind: "own_teams";
+                descendants: boolean;
+            } | {
+                kind: "resource";
+                resourceType: string;
+                resourceId: string;
+            })[];
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: ({
+                kind: "organisation";
+            } | {
+                kind: "team";
+                teamId: string;
+                descendants: boolean;
+            } | {
+                kind: "own_teams";
+                descendants: boolean;
+            } | {
+                kind: "resource";
+                resourceType: string;
+                resourceId: string;
+            })[];
+        }>;
+        relation: import("drizzle-orm/pg-core").PgColumn<{
+            name: "relation";
+            tableName: "authz_grants";
+            dataType: "string";
+            columnType: "PgText";
+            data: "any" | "owner" | "actor" | "subject";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: "any" | "owner" | "actor" | "subject";
+        }>;
+        guest: import("drizzle-orm/pg-core").PgColumn<{
+            name: "guest";
+            tableName: "authz_grants";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        reason: import("drizzle-orm/pg-core").PgColumn<{
+            name: "reason";
+            tableName: "authz_grants";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        expiresAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "expires_at";
+            tableName: "authz_grants";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        revokedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "revoked_at";
+            tableName: "authz_grants";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdBy: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_by";
+            tableName: "authz_grants";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "authz_grants";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/** A revoked grant stays revoked even before its end date; a lapsed one ran out on its own. */
+export type GrantStatus = 'current' | 'lapsed' | 'revoked';
+export interface GuestGrant {
+    /** Ready for `resourceAccess`. Times are epoch milliseconds, so pass `now` as `Date.now()`. */
+    readonly grant: ResourceGrant;
+    readonly reason: string | null;
+    readonly status: GrantStatus;
+    readonly revokedAt: Date | null;
+}
+/**
+ * Every guest grant a tenant has issued in one application, lapsed and revoked ones included, so a
+ * caller that acts on expiry sees the lapse rather than a row that silently disappeared.
+ */
+export declare function guestGrants(tx: DbOrTx, binding: PolicyBinding, tenantId: string, now?: Date): Promise<GuestGrant[]>;