@aventara/access 0.0.0-stage → 1.0.0-rc.1

package/dist/registry/registry.key.js

@@ -0,0 +1,13 @@
+// The registry's keys. Each namespace has one push key and one read-only pull key.
+// A key is 32 random bytes, written `avk_push_…` or `avk_pull_…` so a secret scanner
+// and a reader both see what it is. The registry keeps only its SHA-256 hash: the key
+// itself is in the answer that issued it and nowhere else, never in a table, a log
+// line or a later response.
+import { randomSecret } from "../random-secret.generator.js";
+import { sha256Hex } from "../sha256.digest.js";
+export const KEY_KINDS = ["push", "pull"];
+const KEY = /^avk_(push|pull)_[A-Za-z0-9_-]{43}$/;
+/** A new key of `kind`: 256 random bits from the runtime's CSPRNG. */
+export const newKey = (kind) => randomSecret(`avk_${kind}_`);
+/** The hash the registry stores and looks a key up by; `undefined` for text that is no key. */
+export const keyHashOf = (key) => KEY.test(key) ? `sha256:${sha256Hex(key)}` : undefined;

package/dist/registry/registry.options.d.ts

@@ -0,0 +1,13 @@
+import type { RegistrySettings } from "./access.registry.js";
+/** The `registry` block: `{ enabled: true }` turns the registry on; `{ enabled: false }` is the default. */
+export type AccessRegistryOptions<E extends boolean = boolean> = {
+    readonly enabled: E;
+    /**
+     * Who gives a Resource its owner: `"first-push"` (the default), the first push
+     * that names it as its own unless the operator assigned it already
+     * (`access.registry.assignResource`), or `"assigned"`, the operator alone.
+     */
+    readonly ownership?: "first-push" | "assigned";
+};
+/** The registry's settings when the block turns it on; `undefined` when it is off. */
+export declare const registryOptionsOf: (registry: unknown) => RegistrySettings | undefined;

package/dist/registry/registry.options.js

@@ -0,0 +1,28 @@
+// The `registry` block of `createAccess` and `aventaraAccess()`, checked: `{ enabled: true }` turns the
+// registry on, with `ownership` saying who gives a Resource its owner
+// (`"first-push"`, the default, or `"assigned"`); `{ enabled: false }`, the default,
+// leaves it off.
+import { AccessError } from "../access/access.error.js";
+import { isRecord } from "../policies.compiler.js";
+const OWNERSHIP = ["first-push", "assigned"];
+const KEYS = ["enabled", "ownership"];
+/** The registry's settings when the block turns it on; `undefined` when it is off. */
+export const registryOptionsOf = (registry) => {
+    if (registry === undefined) {
+        return undefined;
+    }
+    if (!isRecord(registry) ||
+        typeof registry.enabled !== "boolean" ||
+        Object.keys(registry).some((key) => !KEYS.includes(key)) ||
+        (registry.ownership !== undefined &&
+            !OWNERSHIP.includes(registry.ownership)) ||
+        (registry.enabled === false && registry.ownership !== undefined)) {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", '`registry` is `{ enabled: true }` (the policy registry: its tables and its routes), optionally with `ownership: "first-push"` (the default) or `"assigned"`, or `{ enabled: false }`, the default.');
+    }
+    return registry.enabled
+        ? {
+            ownership: registry.ownership ??
+                "first-push",
+        }
+        : undefined;
+};

package/dist/registry/registry.refusal.d.ts

@@ -0,0 +1,6 @@
+import { AccessError, type AccessErrorCode } from "../access/access.error.js";
+/** A refusal over HTTP: the error, and the status it is answered with. */
+export declare class AccessRegistryRefusal extends AccessError {
+    readonly status: number;
+    constructor(code: AccessErrorCode, message: string, status: number);
+}

package/dist/registry/registry.refusal.js

@@ -0,0 +1,11 @@
+// A registry refusal over HTTP: the `AccessError` a registry call throws, with the
+// status its route answers it with.
+import { AccessError } from "../access/access.error.js";
+/** A refusal over HTTP: the error, and the status it is answered with. */
+export class AccessRegistryRefusal extends AccessError {
+    status;
+    constructor(code, message, status) {
+        super(code, message);
+        this.status = status;
+    }
+}

package/dist/registry/registry.schema.d.ts

@@ -0,0 +1,238 @@
+/** The models the registry declares, by Better Auth model name. */
+export declare const REGISTRY_MODELS: {
+    readonly namespace: "accessNamespace";
+    readonly key: "accessKey";
+    readonly policyRevision: "accessPolicyRevision";
+    readonly guardrailRevision: "accessGuardrailRevision";
+    readonly head: "accessHead";
+    readonly pushLog: "accessPushLog";
+    readonly owner: "accessResourceOwner";
+    readonly beacon: "accessBeacon";
+};
+/** The registry's tables, in Better Auth's plugin schema form. */
+export declare const registrySchema: {
+    readonly accessNamespace: {
+        readonly fields: {
+            readonly name: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly createdAt: {
+                readonly type: "date";
+                readonly required: true;
+                readonly input: false;
+                readonly defaultValue: () => Date;
+            };
+        };
+    };
+    readonly accessKey: {
+        readonly fields: {
+            readonly namespaceId: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+                readonly references: {
+                    readonly model: "accessNamespace";
+                    readonly field: "id";
+                    readonly onDelete: "restrict";
+                };
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly keyHash: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly slot: {
+                readonly type: "string";
+                readonly required: false;
+                readonly unique: true;
+            };
+            readonly createdAt: {
+                readonly type: "date";
+                readonly required: true;
+                readonly input: false;
+                readonly defaultValue: () => Date;
+            };
+            readonly revokedAt: {
+                readonly type: "date";
+                readonly required: false;
+            };
+        };
+    };
+    readonly accessPolicyRevision: {
+        readonly fields: {
+            readonly hash: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly format: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly file: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly createdAt: {
+                readonly type: "date";
+                readonly required: true;
+                readonly input: false;
+                readonly defaultValue: () => Date;
+            };
+            readonly namespaceId: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+                readonly references: {
+                    readonly model: "accessNamespace";
+                    readonly field: "id";
+                    readonly onDelete: "restrict";
+                };
+            };
+        };
+    };
+    readonly accessGuardrailRevision: {
+        readonly fields: {
+            readonly hash: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly format: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly file: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly createdAt: {
+                readonly type: "date";
+                readonly required: true;
+                readonly input: false;
+                readonly defaultValue: () => Date;
+            };
+        };
+    };
+    readonly accessHead: {
+        readonly fields: {
+            readonly line: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly hash: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly updatedAt: {
+                readonly type: "date";
+                readonly required: true;
+            };
+        };
+    };
+    readonly accessPushLog: {
+        readonly fields: {
+            readonly line: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly keyId: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly hash: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly outcome: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly code: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly count: {
+                readonly type: "number";
+                readonly required: true;
+            };
+            readonly createdAt: {
+                readonly type: "date";
+                readonly required: true;
+                readonly input: false;
+                readonly defaultValue: () => Date;
+            };
+        };
+    };
+    readonly accessBeacon: {
+        readonly fields: {
+            readonly namespaceId: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+                readonly references: {
+                    readonly model: "accessNamespace";
+                    readonly field: "id";
+                    readonly onDelete: "restrict";
+                };
+            };
+            readonly beaconHash: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly slot: {
+                readonly type: "string";
+                readonly required: false;
+                readonly unique: true;
+            };
+            readonly createdAt: {
+                readonly type: "date";
+                readonly required: true;
+                readonly input: false;
+                readonly defaultValue: () => Date;
+            };
+            readonly retiredAt: {
+                readonly type: "date";
+                readonly required: false;
+            };
+        };
+    };
+    readonly accessResourceOwner: {
+        readonly fields: {
+            readonly resource: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly namespaceId: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+                readonly references: {
+                    readonly model: "accessNamespace";
+                    readonly field: "id";
+                    readonly onDelete: "restrict";
+                };
+            };
+            readonly source: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly createdAt: {
+                readonly type: "date";
+                readonly required: true;
+                readonly input: false;
+                readonly defaultValue: () => Date;
+            };
+        };
+    };
+};

package/dist/registry/registry.schema.js

@@ -0,0 +1,127 @@
+// The registry's tables, declared through Better Auth's plugin schema: the Access
+// plugin carries them when `registry: { enabled: true }`, so Better Auth's own
+// migration (or its CLI's `generate` for an ORM's schema) creates them beside Better
+// Auth's, and they are read and written through whatever database adapter the app
+// gave Better Auth. Access names no ORM and writes no SQL.
+//
+// The names follow Better Auth's own plugins (`twoFactor`, `jwks`): camelCase models,
+// which Better Auth's Prisma generator turns into `AccessNamespace` and so on.
+//
+// - `accessNamespace`: one row per namespace, written once.
+// - `accessKey`: a namespace's push and pull keys, as SHA-256 hashes only. Rotating
+//   or revoking a key stamps `revokedAt` and clears its `slot`; a key's row is never
+//   deleted, so a push log entry keeps naming the key that made it. A live key holds
+//   its namespace's slot for its kind (`<namespace id>:push` or `:pull`), unique: two
+//   rotations at once cannot both leave a live key.
+// - `accessResourceOwner`: which namespace owns each Resource, one row per Resource,
+//   its name unique: two pushes at once cannot both claim it. `source` says who
+//   made the row: `push` (the first push that named it, released when the
+//   namespace's head no longer does) or `operator` (`assignResource`, until
+//   `releaseResource`).
+// - `accessPolicyRevision` and `accessGuardrailRevision`: the pushed files, keyed by
+//   their hash and stored in their canonical text, written once and never updated.
+// - `accessHead`: the current revision of each line (a namespace's policies, or the
+//   org's guardrails).
+// - `accessBeacon`: each namespace's beacons, as the SHA-256 hash of
+//   `<namespace>:<value>` its service wrote in its `_aventara_beacon` row and pushed
+//   with its file; the value itself is never stored. The current one holds its
+//   namespace's `slot` (unique); a push with another value retires it (`retiredAt`,
+//   no slot: the namespace moved to another database) and is the current one from
+//   then on. A retired hash never comes back.
+// - `accessPushLog`: every push of a key the registry has, and every guardrails
+//   push, with its outcome; refusals of a key it does not have (or of none) add up
+//   in one row per namespace per minute, its `count`.
+/** The models the registry declares, by Better Auth model name. */
+export const REGISTRY_MODELS = {
+    namespace: "accessNamespace",
+    key: "accessKey",
+    policyRevision: "accessPolicyRevision",
+    guardrailRevision: "accessGuardrailRevision",
+    head: "accessHead",
+    pushLog: "accessPushLog",
+    owner: "accessResourceOwner",
+    beacon: "accessBeacon",
+};
+const createdAt = {
+    type: "date",
+    required: true,
+    input: false,
+    defaultValue: () => new Date(),
+};
+const namespaceReference = {
+    type: "string",
+    required: true,
+    index: true,
+    references: {
+        model: REGISTRY_MODELS.namespace,
+        field: "id",
+        onDelete: "restrict",
+    },
+};
+/** A revision table: the file in its canonical text, under its hash. */
+const revisionFields = {
+    hash: { type: "string", required: true, unique: true },
+    format: { type: "string", required: true },
+    file: { type: "string", required: true },
+    createdAt,
+};
+/** The registry's tables, in Better Auth's plugin schema form. */
+export const registrySchema = {
+    [REGISTRY_MODELS.namespace]: {
+        fields: {
+            name: { type: "string", required: true, unique: true },
+            createdAt,
+        },
+    },
+    [REGISTRY_MODELS.key]: {
+        fields: {
+            namespaceId: namespaceReference,
+            kind: { type: "string", required: true },
+            keyHash: { type: "string", required: true, unique: true },
+            slot: { type: "string", required: false, unique: true },
+            createdAt,
+            revokedAt: { type: "date", required: false },
+        },
+    },
+    [REGISTRY_MODELS.policyRevision]: {
+        fields: { namespaceId: namespaceReference, ...revisionFields },
+    },
+    [REGISTRY_MODELS.guardrailRevision]: {
+        fields: revisionFields,
+    },
+    [REGISTRY_MODELS.head]: {
+        fields: {
+            line: { type: "string", required: true, unique: true },
+            hash: { type: "string", required: true },
+            updatedAt: { type: "date", required: true },
+        },
+    },
+    [REGISTRY_MODELS.pushLog]: {
+        fields: {
+            line: { type: "string", required: true, index: true },
+            keyId: { type: "string", required: false },
+            hash: { type: "string", required: false },
+            outcome: { type: "string", required: true },
+            code: { type: "string", required: false },
+            count: { type: "number", required: true },
+            createdAt,
+        },
+    },
+    [REGISTRY_MODELS.beacon]: {
+        fields: {
+            namespaceId: namespaceReference,
+            beaconHash: { type: "string", required: true, unique: true },
+            slot: { type: "string", required: false, unique: true },
+            createdAt,
+            retiredAt: { type: "date", required: false },
+        },
+    },
+    [REGISTRY_MODELS.owner]: {
+        fields: {
+            resource: { type: "string", required: true, unique: true },
+            namespaceId: namespaceReference,
+            source: { type: "string", required: true },
+            createdAt,
+        },
+    },
+};

package/dist/resources/auth-tables.catalog.d.ts

@@ -0,0 +1,96 @@
+/** A `resources` key: the Better Auth tables it opens as Resources of the app's rules. */
+export type AuthResourceKey = "users" | "members";
+/** What a write through Aventara may set on one opened table, by action. */
+type WritableFields = {
+    /** Fields a create may set (and the row's identifier), or `undefined`: no create. */
+    readonly create?: readonly string[];
+    /** Fields an update may set, or `undefined`: no update. */
+    readonly update?: readonly string[];
+    /** Whether a delete goes through. */
+    readonly delete: boolean;
+};
+/** One table a `resources` key opens: reads go to the app's policies, writes are limited. */
+type OpenedTable = {
+    readonly key: AuthResourceKey;
+    readonly writes: WritableFields;
+    /**
+     * Fields Access governs for writing (`"write"`): read as the rules grant, written
+     * only through a grant that names the field. A role the app's rules read is one.
+     */
+    readonly governed?: readonly string[];
+    /** Where the table comes from, when a plugin adds it: named in the refusal when it is missing. */
+    readonly plugin?: string;
+};
+/** The tables each key opens, by Better Auth model name. */
+export declare const OPENED_TABLES: {
+    readonly [model: string]: OpenedTable;
+};
+/** The tables each key must find in the app's schema, by key. */
+export declare const KEY_TABLES: {
+    readonly [K in AuthResourceKey]: readonly string[];
+};
+/**
+ * The secret columns of Better Auth's tables, by Better Auth model name: no grant
+ * opens them, for reading or writing, on any table, opened or not.
+ */
+export declare const SECRET_COLUMNS: {
+    readonly [model: string]: readonly string[];
+};
+/** One Better Auth table as the app's schema names it. */
+export type AuthTable = {
+    /** Better Auth's model name (`user`, `member`), before the app renames it. */
+    readonly model: string;
+    /** The table's name in Better Auth: its `modelName`, or the model name. */
+    readonly name: string;
+    /** The Resource the app's schema has for it; `undefined` when it has none. */
+    readonly resource: string | undefined;
+    /** Better Auth's field names, to the app's. */
+    readonly fields: ReadonlyMap<string, string>;
+};
+/** One field of a Better Auth table, as `getAuthTables(options)` states it. */
+export type BetterAuthField = {
+    readonly fieldName?: string;
+    /** `false`: a user cannot set it (at sign-up, or with `/update-user`). Absent means they can. */
+    readonly input?: boolean;
+};
+/** Better Auth's tables as `getAuthTables(options)` states them. */
+export type BetterAuthTables = {
+    readonly [model: string]: {
+        readonly modelName?: string;
+        readonly fields: {
+            readonly [field: string]: BetterAuthField;
+        };
+    };
+};
+/**
+ * How Access knows which Resource of the rules' schema is which of Better Auth's
+ * tables.
+ *
+ * - `prisma`: Better Auth runs on its Prisma adapter, which reads a table through
+ *   the Prisma client's delegate named as the table (`modelName`, or the model's own
+ *   name, plus `s` with `usePlural`). The Prisma model behind that delegate (the
+ *   delegate is the model's name with its first letter lower-cased) is the table:
+ *   an exact match, whatever the database names its tables.
+ * - `map`: any other adapter reads the database's tables by their own names, which
+ *   a Prisma schema can give any model name (`@@map`), so the app names each table's
+ *   Resource itself (`resources.authTables`), or `null` for none.
+ */
+export type AuthTableNaming = {
+    readonly kind: "prisma";
+    readonly usePlural: boolean;
+} | {
+    readonly kind: "map";
+    readonly map: {
+        readonly [model: string]: string | null;
+    };
+};
+/**
+ * Better Auth's tables, for the options it is built with (its plugins' tables and
+ * Access's own included), by Better Auth model name, each with the Resource (when
+ * the rules' schema has it, as `naming` says) and the field names the app's schema
+ * has for it (Better Auth's `fieldName`s).
+ */
+export declare const authTablesOf: (tables: BetterAuthTables, schema: {
+    readonly [resource: string]: unknown;
+}, naming: AuthTableNaming) => ReadonlyMap<string, AuthTable>;
+export {};

package/dist/resources/auth-tables.catalog.js

@@ -0,0 +1,110 @@
+// What Access knows about Better Auth's tables (better-auth 1.7.12 to 1.7.14, its plugins, and
+// Access's own plugin tables): which `resources` key opens each one as a Resource of
+// the app's rules, which of its columns are secrets no grant ever opens, and which
+// fields a write through Aventara may set. The names here are Better Auth's own
+// (its model and field names, before an app renames them); `authTablesOf` maps them
+// to the Resource and field names the app's schema has.
+//
+// A table no key opens stays Better Auth's: Access denies every action on it. A
+// write through Aventara is a plain database write: it skips Better Auth's hooks
+// (`databaseHooks`, plugins' `after` hooks), its cookie cache and its secondary
+// storage, so the writes Access lets through are the ones those do not guard:
+// a user's role and an organization's memberships. A role is governed for writing,
+// so only a grant that names it sets it.
+/** The tables each key opens, by Better Auth model name. */
+export const OPENED_TABLES = {
+    // The users: a user's role may be set; creating or deleting a user, and every
+    // other field (name, email, ban), stays with Better Auth's own API.
+    // The role is governed for writing: only a grant that names `User.role` sets it.
+    user: {
+        key: "users",
+        writes: { update: ["role"], delete: false },
+        governed: ["role"],
+    },
+    session: { key: "users", writes: { delete: false } },
+    account: { key: "users", writes: { delete: false } },
+    // The organization plugin's memberships: a membership is created or removed, and
+    // its role changed; the organization itself is read only. The role is governed
+    // for writing: only a grant that names it sets it, at create or update.
+    member: {
+        key: "members",
+        plugin: "organization()",
+        writes: {
+            create: ["organizationId", "userId", "role", "createdAt"],
+            update: ["role"],
+            delete: true,
+        },
+        governed: ["role"],
+    },
+    organization: {
+        key: "members",
+        plugin: "organization()",
+        writes: { delete: false },
+    },
+};
+/** The tables each key must find in the app's schema, by key. */
+export const KEY_TABLES = {
+    users: ["user", "session", "account"],
+    members: ["member", "organization"],
+};
+/**
+ * The secret columns of Better Auth's tables, by Better Auth model name: no grant
+ * opens them, for reading or writing, on any table, opened or not.
+ */
+export const SECRET_COLUMNS = {
+    // The password hash, and the provider's tokens for social sign-in.
+    account: ["password", "accessToken", "refreshToken", "idToken"],
+    // The session token: a bearer of it is signed in.
+    session: ["token"],
+    // Reset, verification, magic-link and OTP values; the identifier carries the
+    // reset token itself (`reset-password:<token>`).
+    verification: ["identifier", "value"],
+    // The JWT signing key (`jwt()`, which createAccess installs).
+    jwks: ["privateKey"],
+    // `twoFactor()`: the TOTP secret and the backup codes.
+    twoFactor: ["secret", "backupCodes"],
+    // `deviceAuthorization()`: the codes a device signs in with.
+    deviceCode: ["deviceCode", "userCode"],
+    // Access's registry (`registry: { enabled: true }`): a namespace key's hash.
+    accessKey: ["keyHash"],
+    // The Access server's ownership beacon: its value proves a reader reaches this
+    // database, so no grant ever reads it.
+    aventaraBeacon: ["value"],
+    // The kiosk profile: a device credential's hashes, and a PIN's.
+    accessKioskDevice: ["secretHash", "previousSecretHash"],
+    accessKioskPin: ["pinHash"],
+    accessKioskRetiredSecret: ["secretHash"],
+};
+/** The Prisma client's delegate for a model: its name with the first letter lower-cased. */
+const delegateOf = (model) => `${model.charAt(0).toLowerCase()}${model.slice(1)}`;
+/**
+ * Better Auth's tables, for the options it is built with (its plugins' tables and
+ * Access's own included), by Better Auth model name, each with the Resource (when
+ * the rules' schema has it, as `naming` says) and the field names the app's schema
+ * has for it (Better Auth's `fieldName`s).
+ */
+export const authTablesOf = (tables, schema, naming) => {
+    const resources = Object.keys(schema);
+    const found = new Map();
+    for (const model of Object.keys(tables)) {
+        const name = tables[model]?.modelName ?? model;
+        let resource;
+        if (naming.kind === "map") {
+            resource = naming.map[model] ?? undefined;
+        }
+        else {
+            const delegate = naming.usePlural ? `${name}s` : name;
+            for (const candidate of resources) {
+                if (delegateOf(candidate) === delegate) {
+                    resource = candidate;
+                }
+            }
+        }
+        const fields = new Map();
+        for (const [field, attribute] of Object.entries(tables[model]?.fields ?? {})) {
+            fields.set(field, attribute.fieldName ?? field);
+        }
+        found.set(model, { model, name, resource, fields });
+    }
+    return found;
+};