@aventara/access 0.0.0-stage → 0.1.0-rc.0

package/dist/registry/access.registry.d.ts

@@ -0,0 +1,173 @@
+import type { AccessGuardrails } from "../guardrails/guardrails-contract.js";
+import type { AccessPolicies, AccessSchemaResourceFacts } from "../policies-contract.js";
+import { type OwnershipMode } from "./ownership.check.js";
+import { type AccessKeyKind } from "./registry.key.js";
+export { AccessRegistryRefusal } from "./registry.refusal.js";
+/** A condition on one field, in Better Auth's adapter form: equal to `value`, or `in` its list. */
+type Where = {
+    readonly field: string;
+    readonly value: string;
+} | {
+    readonly field: string;
+    readonly operator: "in";
+    readonly value: string[];
+};
+/**
+ * The part of Better Auth's database adapter the registry uses: each call goes
+ * through whatever adapter the app gave Better Auth.
+ */
+export type RegistryAdapter = {
+    create<T>(input: {
+        model: string;
+        data: {
+            readonly [field: string]: unknown;
+        };
+    }): Promise<T>;
+    findOne<T>(input: {
+        model: string;
+        where: Where[];
+    }): Promise<T | null>;
+    findMany<T>(input: {
+        model: string;
+        where?: Where[];
+        limit?: number;
+        sortBy?: {
+            field: string;
+            direction: "asc" | "desc";
+        };
+    }): Promise<T[]>;
+    update<T>(input: {
+        model: string;
+        where: Where[];
+        update: {
+            readonly [field: string]: unknown;
+        };
+    }): Promise<T | null>;
+    delete(input: {
+        model: string;
+        where: Where[];
+    }): Promise<void>;
+    transaction<R>(run: (adapter: RegistryAdapter) => Promise<R>): Promise<R>;
+};
+/** The largest policies file a push stores, in bytes of its JSON text: 1 MiB. */
+export declare const MAX_POLICIES_BYTES = 1048576;
+/** A namespace's two keys, as the call that issues them answers: the only time they are seen. */
+export type AccessNamespaceKeys = {
+    readonly namespace: string;
+    readonly push: string;
+    readonly pull: string;
+};
+/** What a push answers: the file's hash, and whether this push stored it (`false`: the registry had it). */
+export type AccessPushResult = {
+    readonly hash: string;
+    readonly created: boolean;
+};
+/** A stored revision, as a read answers it: a namespace's policies file, or the org's guardrails file. */
+type AccessRevision<File = AccessPolicies> = {
+    readonly hash: string;
+    readonly format: string;
+    readonly createdAt: Date;
+    readonly file: File;
+};
+/**
+ * What a namespace reads of another one it reads as foreign: the hash of the
+ * beacon the owner pushed (`null`: none yet), and the owner's schema entry of each
+ * Resource asked for, from its current file.
+ */
+type AccessForeignRead = {
+    readonly owner: string;
+    readonly beacon: string | null;
+    readonly resources: {
+        readonly [resource: string]: AccessSchemaResourceFacts;
+    };
+};
+/** A namespace, as a read answers it: its name and its current revision's hash. */
+type AccessNamespaceInfo = {
+    readonly name: string;
+    readonly createdAt: Date;
+    readonly head: string | null;
+    /** The hash of the namespace's current beacon; `null` when it has pushed none. */
+    readonly beacon: string | null;
+};
+/**
+ * The operator's side of the registry, on an instance built with
+ * `registry: { enabled: true }`. It runs in the server's own process and takes no
+ * key: whoever holds the instance is the operator.
+ */
+export type AccessRegistry = {
+    /**
+     * Adds a namespace and issues its push key and its read-only pull key. The keys
+     * are in this answer only; the registry keeps their hashes.
+     */
+    createNamespace(name: string): Promise<AccessNamespaceKeys>;
+    /** Issues a new key of `kind`; from now on the namespace's previous one is refused. */
+    rotateKey(namespace: string, kind: AccessKeyKind): Promise<string>;
+    /** Refuses the namespace's key of `kind` from now on, until `rotateKey` issues another. */
+    revokeKey(namespace: string, kind: AccessKeyKind): Promise<void>;
+    /**
+     * Pushes the org's guardrails file (`defineGuardrails(...).contract()`, format
+     * `aventara-access/guardrails@1`), which every namespace's key then reads. Each
+     * namespace it names a Resource list for must be one the registry has.
+     */
+    pushGuardrails(file: AccessGuardrails): Promise<AccessPushResult>;
+    /**
+     * Gives `resource` to `namespace`: from now on only that namespace's file names
+     * it as its own, and another namespace's push that does is refused, whoever named
+     * it first. With `ownership: "assigned"` this is the only way a Resource gets an
+     * owner. A namespace whose current file names the Resource as its own keeps that
+     * revision; its next push is checked.
+     */
+    assignResource(resource: string, namespace: string): Promise<void>;
+    /**
+     * Takes `resource` from its owner: with `ownership: "first-push"` the next push
+     * that names it as its own claims it; with `"assigned"` no push may until it is
+     * assigned again.
+     */
+    releaseResource(resource: string): Promise<void>;
+};
+/** How the registry decides who owns a Resource (the `registry` block's `ownership`). */
+export type RegistrySettings = {
+    readonly ownership: OwnershipMode;
+};
+/** The registry over the adapter `adapterOf` resolves (Better Auth's, once it is built). */
+export declare const createRegistry: (adapterOf: () => Promise<RegistryAdapter>, settings?: RegistrySettings) => {
+    operator: AccessRegistry;
+    /**
+     * The namespace a key belongs to, and its kind: what `avaccess pull` reads when
+     * the project has no lock yet. A key that is not one of this registry's, or was
+     * revoked, is refused as a read with it would be.
+     */
+    keyOwner: (key: string | undefined) => Promise<{
+        readonly namespace: string;
+        readonly kind: AccessKeyKind;
+    }>;
+    /**
+     * Whether `key` is `namespace`'s push key: the refusal a push would get
+     * (`ACCESS_KEY_REFUSED`, logged as a push's), or nothing. The routes' mounts ask
+     * it before a push's body is read.
+     */
+    admitPush: (namespace: string, key: string | undefined) => Promise<void>;
+    /** Pushes `body` as `namespace`'s file, with that namespace's push key. */
+    push: (namespace: string, key: string | undefined, body: unknown) => Promise<AccessPushResult>;
+    namespace: (namespace: string, key: string | undefined) => Promise<AccessNamespaceInfo>;
+    revisions: (namespace: string, key: string | undefined) => Promise<{
+        hash: string;
+        format: string;
+        createdAt: Date;
+    }[]>;
+    revision: (namespace: string, key: string | undefined, hash: string) => Promise<AccessRevision<AccessPolicies> | null>;
+    head: (namespace: string, key: string | undefined) => Promise<AccessRevision<AccessPolicies> | null>;
+    /**
+     * What the namespace reads of `owner`: of the Resources its current file reads
+     * as `owner`'s (`{ "foreign": "<owner>" }`), `owner`'s schema entry of each one
+     * `resources` names, and the hash of the beacon `owner` pushed. Anything else
+     * (an owner the file does not read, a Resource it does not read as that
+     * owner's, an owner that does not own it or has no file describing it) gets one
+     * and the same refusal, which tells nothing of who owns what. Every read is
+     * logged with its key.
+     */
+    foreign: (namespace: string, key: string | undefined, owner: string, resources: readonly string[]) => Promise<AccessForeignRead>;
+    guardrails: (namespace: string, key: string | undefined) => Promise<AccessRevision<AccessGuardrails> | null>;
+};
+/** The registry `createRegistry` builds. */
+export type Registry = ReturnType<typeof createRegistry>;