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

package/dist/audit/audit.schema.d.ts

@@ -0,0 +1,143 @@
+/** The model the audit log declares, by Better Auth model name. */
+export declare const AUDIT_MODEL = "accessAudit";
+/** The audit table, in Better Auth's plugin schema form. */
+export declare const auditSchema: {
+    readonly accessAudit: {
+        readonly fields: {
+            readonly at: {
+                readonly type: "date";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly userId: {
+                readonly type: "string";
+                readonly required: false;
+                readonly index: true;
+            };
+            readonly resource: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly action: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly allowed: {
+                readonly type: "boolean";
+                readonly required: false;
+            };
+            readonly reason: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly route: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly target: {
+                readonly type: "string";
+                readonly required: false;
+                readonly index: true;
+            };
+            readonly impersonatedBy: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly suppressed: {
+                readonly type: "number";
+                readonly required: false;
+            };
+            readonly windowStart: {
+                readonly type: "date";
+                readonly required: false;
+            };
+            readonly windowEnd: {
+                readonly type: "date";
+                readonly required: false;
+            };
+            readonly origin: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+    };
+};
+/** The audit table with the kiosk profile's columns. */
+export declare const kioskAuditSchema: {
+    readonly accessAudit: {
+        readonly fields: {
+            readonly deviceId: {
+                readonly type: "string";
+                readonly required: false;
+                readonly index: true;
+            };
+            readonly previousUserId: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly at: {
+                readonly type: "date";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly userId: {
+                readonly type: "string";
+                readonly required: false;
+                readonly index: true;
+            };
+            readonly resource: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly action: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly allowed: {
+                readonly type: "boolean";
+                readonly required: false;
+            };
+            readonly reason: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly route: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly target: {
+                readonly type: "string";
+                readonly required: false;
+                readonly index: true;
+            };
+            readonly impersonatedBy: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly suppressed: {
+                readonly type: "number";
+                readonly required: false;
+            };
+            readonly windowStart: {
+                readonly type: "date";
+                readonly required: false;
+            };
+            readonly windowEnd: {
+                readonly type: "date";
+                readonly required: false;
+            };
+            readonly origin: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+    };
+};

package/dist/audit/audit.schema.js

@@ -0,0 +1,50 @@
+// The audit table, declared through Better Auth's plugin schema: the Access plugin
+// carries it when `audit: true`, so Better Auth's own migration (or its CLI's
+// `generate` for an ORM's schema) creates it beside Better Auth's tables, and events
+// are written through whatever database adapter the app gave Better Auth. With
+// `audit: { sink }` the plugin declares no table.
+//
+// The name follows the registry's tables (and Better Auth's own plugins, `twoFactor`,
+// `jwks`): a camelCase model, which Better Auth's Prisma generator turns into
+// `AccessAudit`.
+//
+// `userId` is a plain column, not a reference to Better Auth's `user`: a row outlives
+// the user it names, and deleting a user never touches the log.
+/** The model the audit log declares, by Better Auth model name. */
+export const AUDIT_MODEL = "accessAudit";
+const optionalString = { type: "string", required: false };
+/** The audit table, in Better Auth's plugin schema form. */
+export const auditSchema = {
+    [AUDIT_MODEL]: {
+        fields: {
+            at: { type: "date", required: true, index: true },
+            kind: { type: "string", required: true },
+            userId: { type: "string", required: false, index: true },
+            resource: optionalString,
+            action: optionalString,
+            allowed: { type: "boolean", required: false },
+            reason: optionalString,
+            route: optionalString,
+            target: { type: "string", required: false, index: true },
+            impersonatedBy: optionalString,
+            suppressed: { type: "number", required: false },
+            windowStart: { type: "date", required: false },
+            windowEnd: { type: "date", required: false },
+            origin: { type: "string", required: true },
+        },
+    },
+};
+/**
+ * The audit table's columns for the kiosk profile's events, added to it only on that
+ * profile: the device, and the user a switch replaced.
+ */
+const kioskAuditFields = {
+    deviceId: { type: "string", required: false, index: true },
+    previousUserId: optionalString,
+};
+/** The audit table with the kiosk profile's columns. */
+export const kioskAuditSchema = {
+    [AUDIT_MODEL]: {
+        fields: { ...auditSchema[AUDIT_MODEL].fields, ...kioskAuditFields },
+    },
+};

package/dist/auth/index.d.ts

@@ -0,0 +1,12 @@
+export { type Access, type AccessBetterAuthOptions, type AccessOptions, type AccessPoliciesOptions, type AccessRegistryOptions, type AccessRules, createAccess, } from "../access/access.factory.js";
+export type { AccessClaimsAnswer, AccessClaimsSource, AccessIdentity, } from "../access/claims.mapper.js";
+export type { AccessKioskProfile, AccessProfileKind, AccessProfileOptions, } from "../access/profile.policy.js";
+export type { AccessAuditEvent, AccessAuditOptions, } from "../audit/audit-event.js";
+export type { AccessKiosk, AccessKioskDevice, } from "../kiosk/kiosk.plugin.js";
+export { type AccessAgent, agentOf } from "../mcp/agent.grant.js";
+export type { AccessAgentIdentity, AccessMcpAuthorization, AccessMcpOptions, } from "../mcp/mcp-options.js";
+export type { AccessArgon2idProfile } from "../passwords/argon2id.hasher.js";
+export type { AccessPasswordsOptions } from "../passwords/passwords.options.js";
+export type { AccessNamespaceKeys, AccessPushResult, AccessRegistry, } from "../registry/access.registry.js";
+export type { AccessKeyKind } from "../registry/registry.key.js";
+export type { AccessResourcesOptions } from "../resources/auth-tables.guard.js";

package/dist/auth/index.js

@@ -0,0 +1,2 @@
+export { createAccess, } from "../access/access.factory.js";
+export { agentOf } from "../mcp/agent.grant.js";

package/dist/aventara-where.translator.d.ts

@@ -0,0 +1,19 @@
+import type { AccessComparison } from "./policies-contract.js";
+import type { Resolved } from "./scope.resolver.js";
+/** A fragment of Aventara's `where` (core's `AvPolicyWhere`, by shape). */
+export type AccessWhere = {
+    readonly [key: string]: unknown;
+};
+/** The Aventara filter operator a comparison is written with. */
+export declare const operatorOf: (cmp: AccessComparison) => string;
+/**
+ * Sets `key` on `target` as its own data member. An assignment would read
+ * `__proto__` as the prototype setter and drop the condition.
+ */
+export declare const defineMember: (target: Record<string, unknown>, key: string, value: unknown) => void;
+/** Merges fragments into one object when no key repeats; otherwise `undefined`. */
+export declare const mergeWhere: (fragments: readonly AccessWhere[]) => AccessWhere | undefined;
+/** Translates a row condition that is neither `true` nor `false` at its root. */
+export declare const translateWhere: (node: Resolved) => AccessWhere;
+/** A seam answer: `true` every row, `false` none, or a `where`. */
+export declare const translateAnswer: (node: Resolved) => boolean | AccessWhere;

package/dist/aventara-where.translator.js

@@ -0,0 +1,87 @@
+// Folded condition → Aventara's `where` grammar, with explicit operators
+// (`{ equals: … }`), as core validates it against the Core Contract.
+const OPERATOR = {
+    eq: "equals",
+    ne: "not",
+    in: "in",
+    notIn: "notIn",
+};
+/** The Aventara filter operator a comparison is written with. */
+export const operatorOf = (cmp) => OPERATOR[cmp];
+const isField = (node) => node.k === "cmp" ||
+    node.k === "rel" ||
+    node.k === "some" ||
+    node.k === "every" ||
+    node.k === "none";
+const keyOf = (node) => (node.k === "cmp" ? node.field : node.relation);
+/**
+ * Sets `key` on `target` as its own data member. An assignment would read
+ * `__proto__` as the prototype setter and drop the condition.
+ */
+export const defineMember = (target, key, value) => {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+};
+/** An object with one own member. */
+const one = (key, value) => {
+    const where = {};
+    defineMember(where, key, value);
+    return where;
+};
+/** Merges fragments into one object when no key repeats; otherwise `undefined`. */
+export const mergeWhere = (fragments) => {
+    const merged = {};
+    for (const fragment of fragments) {
+        for (const [key, value] of Object.entries(fragment)) {
+            if (Object.hasOwn(merged, key)) {
+                return undefined;
+            }
+            defineMember(merged, key, value);
+        }
+    }
+    return merged;
+};
+/** Translates a row condition that is neither `true` nor `false` at its root. */
+export const translateWhere = (node) => {
+    switch (node.k) {
+        case "true":
+            return {};
+        case "false":
+            // Aventara's `where` has no `false`: the empty `OR` is its one way to match no
+            // row, and an ORM reads it so.
+            return { OR: [] };
+        case "cmp":
+            return one(node.field, {
+                [operatorOf(node.cmp)]: Array.isArray(node.value)
+                    ? [...node.value]
+                    : node.value,
+            });
+        case "rel":
+            return one(node.relation, translateWhere(node.where));
+        case "some":
+        case "every":
+        case "none":
+            return one(node.relation, { [node.k]: translateWhere(node.where) });
+        case "not":
+            return { NOT: translateWhere(node.arg) };
+        case "or":
+            return { OR: node.args.map(translateWhere) };
+        case "all":
+            return { AND: node.args.map(translateWhere) };
+        case "and": {
+            // Written by the author as one object: written back as one when every part is
+            // a field condition and no field repeats.
+            if (node.args.every(isField) &&
+                new Set(node.args.map(keyOf)).size === node.args.length) {
+                return mergeWhere(node.args.map(translateWhere));
+            }
+            return { AND: node.args.map(translateWhere) };
+        }
+    }
+};
+/** A seam answer: `true` every row, `false` none, or a `where`. */
+export const translateAnswer = (node) => node.k === "true" ? true : node.k === "false" ? false : translateWhere(node);

package/dist/beacon/beacon.check.d.ts

@@ -0,0 +1,59 @@
+/** Reads a namespace's beacon row, through the service's own connection. */
+export type AccessBeaconReader = {
+    /**
+     * The `value` of `namespace`'s row in `_aventara_beacon`, as this service's
+     * connection reads it; `null` when there is none.
+     */
+    read(namespace: string): Promise<string | null>;
+};
+/**
+ * One environment's beacon pins, `avAccess.beacons.<environment>.json` as
+ * `avaccess pull --env <environment>` writes it: the hash of the beacon each
+ * namespace the rules read as foreign pushed from that environment's database.
+ * `format` is typed as a string so the file imported as JSON is one as it is.
+ */
+export type AccessBeaconPins = {
+    /** `"aventara-access/beacons@1"`. */
+    readonly format: string;
+    /** The namespace that reads the others: the lock's. */
+    readonly namespace: string;
+    /** The environment the pins were pulled for: `production`, `staging`, … */
+    readonly environment: string;
+    /** Each owner namespace's beacon hash, `sha256:<hex>`. */
+    readonly beacons: {
+        readonly [namespace: string]: string;
+    };
+};
+/** The format marker of every beacon pins file. */
+export declare const BEACON_PINS_FORMAT = "aventara-access/beacons@1";
+/**
+ * The error a generated client throws when its beacons have not passed, shaped as
+ * `AccessError` is (`name`, `code`, a message that starts `Aventara Access:`): the
+ * client imports nothing, so it cannot throw the class itself.
+ */
+export declare const beaconMismatch: (message: string) => Error & {
+    readonly code: "ACCESS_BEACON_MISMATCH";
+};
+/** A beacon: `avb_` and 32 random bytes in base64url. */
+export declare const BEACON: RegExp;
+/** A pinned beacon hash: `sha256:` and 64 lowercase hex digits. */
+export declare const BEACON_HASH: RegExp;
+/**
+ * A beacon's hash, as the registry and the pins name it: `sha256:<hex>` of
+ * `<namespace>:<value>`. The namespace is bound in: a value registered under one
+ * namespace never matches, or collides with, another namespace's beacon.
+ */
+export declare const beaconHashOf: (namespace: string, value: string) => Promise<string>;
+/**
+ * What is wrong with `pins` as `namespace`'s beacon pins of `environment` for the
+ * `owners` its rules read as foreign: its format and members, its namespace, its
+ * environment, a `sha256:` hash for every owner; `undefined` when nothing is.
+ */
+export declare const beaconPinsProblem: (namespace: string, owners: readonly string[], pins: unknown, environment: unknown) => string | undefined;
+/**
+ * What is wrong with the beacons of `owners` (the namespaces `namespace`'s rules
+ * read as foreign), held to `pins` (which must be `environment`'s) and read through
+ * `reader`; `undefined` when every
+ * owner's row is there and hashes to its pin. Each owner is read once, in order.
+ */
+export declare const beaconProblem: (namespace: string, owners: readonly string[], pins: unknown, environment: unknown, reader: AccessBeaconReader) => Promise<string | undefined>;

package/dist/beacon/beacon.check.js

@@ -0,0 +1,128 @@
+// The ownership beacon's check, as a service runs it when it starts: each namespace
+// whose Resources the rules read as `foreign` has one row in `_aventara_beacon`,
+// written once by that namespace's own service with a random value, and the
+// registry knows the value's hash. A database's beacons are its own, so their
+// hashes are pinned per environment, apart from `avAccess.lock.json` (which holds
+// against any registry): `avaccess pull --env <name>` writes them to
+// `avAccess.beacons.<name>.json` (`AccessBeaconPins`), or the deploy hands the same
+// object in from its environment. At startup the service reads each owner's row
+// through its own connection: the row is there and hashes to the pin only when the
+// service reaches the owner's database. Anything else (no row, another value, a
+// value that is no beacon, an owner with no pin) means the foreign facts would come
+// from somewhere the owner does not write, and the service refuses to decide.
+//
+// The check reads through an object the app hands in (`AccessBeaconReader`): the
+// engine and the generated client have no database connection of their own and
+// name no ORM. This module imports nothing and reaches no runtime API but WebCrypto's
+// digest, so `avaccess generate` copies it into a generated client as it is.
+/** The format marker of every beacon pins file. */
+export const BEACON_PINS_FORMAT = "aventara-access/beacons@1";
+/**
+ * The error a generated client throws when its beacons have not passed, shaped as
+ * `AccessError` is (`name`, `code`, a message that starts `Aventara Access:`): the
+ * client imports nothing, so it cannot throw the class itself.
+ */
+export const beaconMismatch = (message) => Object.assign(new Error(`Aventara Access: ${message}`), {
+    name: "AccessError",
+    code: "ACCESS_BEACON_MISMATCH",
+});
+/** A beacon: `avb_` and 32 random bytes in base64url. */
+export const BEACON = /^avb_[A-Za-z0-9_-]{43}$/;
+/** A pinned beacon hash: `sha256:` and 64 lowercase hex digits. */
+export const BEACON_HASH = /^sha256:[0-9a-f]{64}$/;
+/** A namespace or environment name: a lowercase letter, then lowercase letters, digits, `_` or `-`. */
+const NAME = /^[a-z][a-z0-9_-]{0,62}$/;
+const PIN_MEMBERS = ["format", "namespace", "environment", "beacons"];
+/**
+ * A beacon's hash, as the registry and the pins name it: `sha256:<hex>` of
+ * `<namespace>:<value>`. The namespace is bound in: a value registered under one
+ * namespace never matches, or collides with, another namespace's beacon.
+ */
+export const beaconHashOf = async (namespace, value) => {
+    const runtime = globalThis;
+    const digest = await runtime.crypto.subtle.digest("SHA-256", new runtime.TextEncoder().encode(`${namespace}:${value}`));
+    let hex = "";
+    for (const byte of new Uint8Array(digest)) {
+        hex += byte.toString(16).padStart(2, "0");
+    }
+    return `sha256:${hex}`;
+};
+/**
+ * What is wrong with `pins` as `namespace`'s beacon pins of `environment` for the
+ * `owners` its rules read as foreign: its format and members, its namespace, its
+ * environment, a `sha256:` hash for every owner; `undefined` when nothing is.
+ */
+export const beaconPinsProblem = (namespace, owners, pins, environment) => {
+    if (typeof environment !== "string" || !NAME.test(environment)) {
+        return `the environment the service runs in is ${JSON.stringify(environment) ?? "missing"}, which is not an environment name (a lowercase letter, then lowercase letters, digits, "_" or "-"): name it, such as "production", and hand in that environment's pins`;
+    }
+    const file = pins;
+    if (typeof file !== "object" || file === null || Array.isArray(file)) {
+        return "the beacon pins are an object, as `avaccess pull --env <environment>` writes avAccess.beacons.<environment>.json";
+    }
+    if (file.format !== BEACON_PINS_FORMAT) {
+        return `the beacon pins' format is "${BEACON_PINS_FORMAT}"; it was ${JSON.stringify(file.format) ?? "missing"}`;
+    }
+    const unknown = Object.keys(file).filter((member) => !PIN_MEMBERS.includes(member));
+    if (unknown.length > 0) {
+        return `the beacon pins have \`format\`, \`namespace\`, \`environment\` and \`beacons\`; they do not take ${unknown.map((member) => `\`${member}\``).join(", ")}`;
+    }
+    if (file.namespace !== namespace) {
+        return `the beacon pins are namespace ${JSON.stringify(file.namespace)}'s, and the rules are namespace "${namespace}"'s: pull this project's own pins with \`avaccess pull --env <environment>\``;
+    }
+    if (file.environment !== environment) {
+        return `the beacon pins are environment ${JSON.stringify(file.environment)}'s, and the service runs in environment "${environment}": hand in avAccess.beacons.${environment}.json`;
+    }
+    const beacons = file.beacons;
+    if (typeof beacons !== "object" ||
+        beacons === null ||
+        Array.isArray(beacons) ||
+        Object.entries(beacons).some(([owner, hash]) => !NAME.test(owner) ||
+            owner === namespace ||
+            typeof hash !== "string" ||
+            !BEACON_HASH.test(hash))) {
+        return "the beacon pins' `beacons` maps each other namespace whose Resources the rules read to its beacon's `sha256:` hash";
+    }
+    const missing = owners.filter((owner) => !Object.hasOwn(beacons, owner));
+    if (missing.length > 0) {
+        return `the rules read ${missing.map((owner) => `namespace "${owner}"'s`).join(" and ")} Resources as foreign, and the beacon pins of environment "${file.environment}" hold no beacon of ${missing.length === 1 ? "it" : "them"}: pull again with \`avaccess pull --env ${file.environment} --beacon <module>\``;
+    }
+    return undefined;
+};
+/**
+ * What is wrong with the beacons of `owners` (the namespaces `namespace`'s rules
+ * read as foreign), held to `pins` (which must be `environment`'s) and read through
+ * `reader`; `undefined` when every
+ * owner's row is there and hashes to its pin. Each owner is read once, in order.
+ */
+export const beaconProblem = async (namespace, owners, pins, environment, reader) => {
+    const invalid = beaconPinsProblem(namespace, owners, pins, environment);
+    if (invalid !== undefined) {
+        return invalid;
+    }
+    if (typeof reader !== "object" ||
+        reader === null ||
+        typeof reader.read !== "function") {
+        return "the beacon reader is `{ read(namespace) }`, which reads a namespace's row in _aventara_beacon through this service's own connection";
+    }
+    const { beacons } = pins;
+    for (const owner of [...owners].sort()) {
+        let value;
+        try {
+            value = await reader.read(owner);
+        }
+        catch (error) {
+            return `reading namespace "${owner}"'s row in _aventara_beacon failed (${String(error?.message ?? error)}): this service cannot show it reaches "${owner}"'s database`;
+        }
+        if (value === null || value === undefined) {
+            return `this service's connection reads no row of namespace "${owner}" in _aventara_beacon, so it does not reach "${owner}"'s database: the rules read "${owner}"'s Resources as foreign, which works only within one database. Point the service at that database, or carry the fact in a JWT claim instead`;
+        }
+        if (typeof value !== "string" || !BEACON.test(value)) {
+            return `namespace "${owner}"'s row in _aventara_beacon holds no beacon (avb_ and 43 base64url characters): it was changed outside the service that writes it`;
+        }
+        if ((await beaconHashOf(owner, value)) !== beacons[owner]) {
+            return `namespace "${owner}"'s beacon, as this service's connection reads it, is not the one the beacon pins of environment "${environment}" hold: the service reaches another database than "${owner}"'s in that environment. Check that the pins are this environment's, pull them again with \`avaccess pull --env ${environment} --beacon <module>\` (it refuses while the databases differ), or carry the fact in a JWT claim instead`;
+        }
+    }
+    return undefined;
+};

package/dist/beacon/beacon.schema.d.ts

@@ -0,0 +1,41 @@
+import type { AccessBeaconStore } from "./beacon.store.js";
+/** The beacon table, in Better Auth's plugin schema form. */
+export declare const beaconSchema: {
+    readonly aventaraBeacon: {
+        readonly fields: {
+            readonly namespace: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly value: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly createdAt: {
+                readonly type: "date";
+                readonly required: true;
+                readonly input: false;
+                readonly defaultValue: () => Date;
+            };
+        };
+    };
+};
+/** The part of Better Auth's adapter the beacon store uses. */
+export type BeaconAdapter = {
+    findOne<T>(input: {
+        model: string;
+        where: {
+            field: string;
+            value: string;
+        }[];
+    }): Promise<T | null>;
+    create<T>(input: {
+        model: string;
+        data: {
+            readonly [field: string]: unknown;
+        };
+    }): Promise<T>;
+};
+/** The beacon store over the adapter `adapterOf` resolves (Better Auth's, once built). */
+export declare const adapterBeaconStore: (adapterOf: () => Promise<BeaconAdapter>) => AccessBeaconStore;

package/dist/beacon/beacon.schema.js

@@ -0,0 +1,48 @@
+// The Access server's own beacon table, declared through Better Auth's plugin schema:
+// when the registry is on and the instance's rules name a namespace (the Access
+// server is then one of the org's namespaces, its Resources Better Auth's tables),
+// the Access plugin carries it, so Better Auth's own migration (or its CLI's
+// `generate`) creates it beside Better Auth's tables, and `access.beacon` reads and
+// writes its row through whatever adapter the app gave Better Auth.
+//
+// Its name follows Access's other tables (`accessAudit`, `accessKey`): the camelCase
+// model `aventaraBeacon`, which Better Auth's Prisma generator writes as
+// `model AventaraBeacon { … @@map("aventaraBeacon") }`. A service's own table may be
+// called `_aventara_beacon`; Better Auth's generator would write that name as the
+// Prisma model's own (`model _aventara_beacon`), which Prisma refuses, so the Access
+// server's is not. The generated client's `prismaBeacon` reads either through the
+// `AventaraBeacon` model's delegate. The auth-tables guard keeps the table closed and
+// its `value` sealed.
+/** The beacon table's Better Auth model name. */
+const BEACON_MODEL = "aventaraBeacon";
+/** The beacon table, in Better Auth's plugin schema form. */
+export const beaconSchema = {
+    [BEACON_MODEL]: {
+        fields: {
+            namespace: { type: "string", required: true, unique: true },
+            value: { type: "string", required: true },
+            createdAt: {
+                type: "date",
+                required: true,
+                input: false,
+                defaultValue: () => new Date(),
+            },
+        },
+    },
+};
+/** The beacon store over the adapter `adapterOf` resolves (Better Auth's, once built). */
+export const adapterBeaconStore = (adapterOf) => ({
+    read: async (namespace) => {
+        const row = await (await adapterOf()).findOne({
+            model: BEACON_MODEL,
+            where: [{ field: "namespace", value: namespace }],
+        });
+        return typeof row?.value === "string" ? row.value : null;
+    },
+    create: async (namespace, value) => {
+        await (await adapterOf()).create({
+            model: BEACON_MODEL,
+            data: { namespace, value },
+        });
+    },
+});

package/dist/beacon/beacon.store.d.ts

@@ -0,0 +1,29 @@
+import type { AccessBeaconReader } from "./beacon.check.js";
+/** The beacon table's name. */
+export declare const BEACON_TABLE = "_aventara_beacon";
+/** Reads and writes beacon rows, through the service's own data layer. */
+export type AccessBeaconStore = AccessBeaconReader & {
+    /**
+     * Writes `namespace`'s row with `value`, once: when the namespace has a row
+     * already, it throws (a unique `namespace`), and the row stays as it was.
+     */
+    create(namespace: string, value: string): Promise<void>;
+};
+/** A new beacon: 256 random bits from the runtime's CSPRNG, written `avb_…`. */
+export declare const newBeacon: () => string;
+/** Whether `value` is a beacon. */
+export declare const isBeacon: (value: unknown) => value is string;
+/**
+ * The namespace's own beacon, for its push: a new row written now when the
+ * namespace has none, or the row it has when its hash is the one the registry holds
+ * for the namespace (`registered`, `null` when it holds none). A row this service
+ * did not write and the registry does not know is never adopted: another service
+ * with write access to the table (a co-tenant of a shared schema) could have planted
+ * it, so it is refused (`ACCESS_BEACON_MISMATCH`) until an operator verifies it or
+ * deletes it, and the next push writes a new one. A row whose value is no beacon is
+ * refused too, never overwritten.
+ */
+export declare const ensureBeacon: (store: AccessBeaconStore, namespace: string, registered: string | null) => Promise<{
+    readonly value: string;
+    readonly created: boolean;
+}>;