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

package/src/policies-contract.ts

@@ -0,0 +1,215 @@
+// The declarative policies file, format `aventara-access/policies@1`. The builder
+// compiles to it and the engine runs from it alone. It is passive JSON: no closures,
+// no claim values, no provider names. `@1` is frozen: a change to its shape is `policies@2` beside it, never an
+// edit of `@1`. Its canonical byte form and hash are `policies.hash.ts`'s.
+
+/** The format marker of every `@1` file. */
+export const POLICIES_FORMAT = "aventara-access/policies@1";
+
+/** The format marker of the unstable v0 files, refused by name (no users, no shim). */
+export const RETIRED_POLICIES_FORMAT = "aventara-access/policies@0";
+
+/** The four standard operations a rule names. */
+export type AccessAction = "read" | "create" | "update" | "delete";
+
+/** The layer a request runs under (core's `AvRequestOrigin`, copied by shape). */
+export type AccessOrigin = "application" | "client" | "agent";
+
+/** The two built-in subjects: `signedIn` (a non-null principal) and `anyone` (null included). */
+export type AccessBuiltInSubject = "signedIn" | "anyone";
+
+/** A literal a rule compares with. */
+export type AccessLiteral = string | number | boolean | null;
+
+/** A value read off the principal at question time (`me.id` → `{ principal: ["id"] }`). */
+export type AccessPrincipalOperand = {
+	readonly principal: readonly [string, ...string[]];
+};
+
+/** What a field comparison compares with. */
+export type AccessOperand = AccessLiteral | AccessPrincipalOperand;
+
+/** The comparisons a rule may make. Each maps one-to-one to an Aventara filter operator. */
+export type AccessComparison = "eq" | "ne" | "in" | "notIn";
+
+/**
+ * A row condition in Access's neutral form. Field names are the Resource's own;
+ * a relation step names its target so the file needs no schema to walk it.
+ */
+export type AccessPredicate =
+	| { readonly op: "true" }
+	| { readonly op: "false" }
+	| { readonly op: "and"; readonly args: readonly AccessPredicate[] }
+	| { readonly op: "or"; readonly args: readonly AccessPredicate[] }
+	| { readonly op: "not"; readonly arg: AccessPredicate }
+	| {
+			readonly op: "cmp";
+			readonly field: string;
+			readonly cmp: AccessComparison;
+			readonly value: AccessOperand | readonly AccessOperand[];
+	  }
+	| {
+			readonly op: "rel";
+			readonly relation: string;
+			readonly target: string;
+			readonly where: AccessPredicate;
+	  }
+	| {
+			readonly op: "some" | "every" | "none";
+			readonly relation: string;
+			readonly target: string;
+			readonly where: AccessPredicate;
+	  }
+	| { readonly op: "role"; readonly role: string };
+
+/** A condition on the principal alone: its claims and the request's origin. */
+export type AccessPrincipalCondition =
+	| { readonly op: "and"; readonly args: readonly AccessPrincipalCondition[] }
+	| {
+			readonly op: "cmp";
+			readonly claim: readonly [string, ...string[]];
+			readonly cmp: "eq";
+			readonly value: AccessLiteral;
+	  }
+	| { readonly op: "origin"; readonly value: AccessOrigin };
+
+/** A role: global (read from claims) or held on a row of one Resource. */
+export type AccessRoleDefinition =
+	| { readonly global: AccessPrincipalCondition }
+	| { readonly on: string; readonly where: AccessPredicate };
+
+/** One grant. Any grant allows (default deny). */
+export type AccessGrantRule = {
+	readonly id: string;
+	readonly subjects: readonly string[];
+	readonly actions: readonly AccessAction[];
+	readonly resource: string;
+	/** The to-one relation whose target holds each subject's row role. */
+	readonly in?: string;
+	readonly where?: AccessPredicate;
+	/** Governed fields this grant opens, as `Resource.field`. */
+	readonly fields?: readonly string[];
+	/** Fields this grant does not let a create or update write. */
+	readonly write?: { readonly except: readonly string[] };
+	/** A condition the row an update leaves must still meet. */
+	readonly after?: AccessPredicate;
+};
+
+/** One deny. Any deny wins over every grant. */
+export type AccessDenyRule = {
+	readonly id: string;
+	readonly actions: "*" | readonly AccessAction[];
+	readonly resource: string;
+	readonly where?: AccessPredicate;
+	readonly if?: AccessPrincipalCondition;
+};
+
+/** A relation as the engine needs it: where it leads, and the reference pairs when this end holds them. */
+export type AccessSchemaRelationFact = {
+	readonly target: string;
+	readonly cardinality: "one" | "many";
+	readonly referenceFields?: readonly [string, ...string[]];
+	readonly references?: readonly [string, ...string[]];
+};
+
+/** The schema facts the engine reads, per Resource. */
+export type AccessSchemaResourceFacts = {
+	readonly identifiers: readonly (readonly string[])[];
+	readonly fields: readonly string[];
+	/**
+	 * The scalar fields that may hold NULL, when there are any. A scope negates a
+	 * comparison on one of them null-safely (`NOT (f = v) OR f IS NULL`), so it keeps
+	 * the rows `can` keeps.
+	 */
+	readonly nullable?: readonly string[];
+	/**
+	 * The scalar fields `can` compares by their type rather than by their JavaScript
+	 * value, when there are any: a `decimal` as its canonical decimal digits (a decimal
+	 * object, a string and a number alike), a `datetime` as its instant, a `bigint`
+	 * exactly. A file without `types` has none of them.
+	 */
+	readonly types?: {
+		readonly [field: string]: "bigint" | "datetime" | "decimal";
+	};
+	readonly relations: { readonly [relation: string]: AccessSchemaRelationFact };
+	/**
+	 * The namespace that owns this Resource, when it is not this file's. A foreign
+	 * Resource is read in conditions and never granted on.
+	 */
+	readonly foreign?: string;
+};
+
+/** A claim's type, never its value. */
+export type AccessClaimType = {
+	readonly scalar: "string" | "number" | "boolean";
+};
+
+/**
+ * The `@1` policies file. `Governed` keeps the `govern` block's literal type through
+ * the builder: per Resource, the list form (each field governed for reading and
+ * writing) or the object form (a mode per field).
+ */
+export type AccessPolicies<
+	Governed extends {
+		readonly [resource: string]:
+			| readonly string[]
+			| { readonly [field: string]: "read" | "write" | "both" };
+	} = {
+		readonly [resource: string]: readonly string[];
+	},
+> = {
+	readonly format: typeof POLICIES_FORMAT;
+	/** The namespace that owns this file's Resources. A single app needs none. */
+	readonly namespace?: string;
+	readonly claims: { readonly [claim: string]: AccessClaimType };
+	readonly schema: { readonly [resource: string]: AccessSchemaResourceFacts };
+	readonly roles: { readonly [role: string]: AccessRoleDefinition };
+	/** Every governed field, by Resource, whatever its mode. */
+	readonly govern: {
+		readonly [R in keyof Governed]: Governed[R] extends readonly string[]
+			? Governed[R]
+			: readonly (keyof Governed[R] & string)[];
+	};
+	/**
+	 * The governed fields governed for one access only, by Resource: `"write"`, read by
+	 * default and written only through a grant that names the field; `"read"`, written
+	 * by default and read only through a grant that names it. A governed field with no
+	 * entry is governed for both, and a file without `governModes` has no other kind.
+	 */
+	readonly governModes?: {
+		readonly [resource: string]: {
+			readonly [field: string]: "read" | "write";
+		};
+	};
+	readonly grants: readonly AccessGrantRule[];
+	readonly denies: readonly AccessDenyRule[];
+};
+
+/**
+ * A policies file as a JSON import types it: `resolveJsonModule` widens `format` to
+ * `string` and each tuple to an array, so the file `avaccess pull` wrote, imported
+ * with `import policies from "./access/blog.policies.json" with { type: "json" }`,
+ * is not an `AccessPolicies`. `policies.rules` and `createAccessEngine` take it as it
+ * is: only its outline is typed, and the engine checks the rest when it is built.
+ */
+export type AccessPoliciesJson<
+	Governed extends {
+		readonly [resource: string]:
+			| readonly string[]
+			| { readonly [field: string]: "read" | "write" | "both" };
+	} = {
+		readonly [resource: string]: readonly string[];
+	},
+> = {
+	readonly format: string;
+	readonly namespace?: string;
+	readonly claims: { readonly [claim: string]: { readonly scalar: string } };
+	readonly schema: { readonly [resource: string]: object };
+	readonly roles: { readonly [role: string]: object };
+	readonly govern: Governed;
+	readonly governModes?: {
+		readonly [resource: string]: { readonly [field: string]: string };
+	};
+	readonly grants: readonly object[];
+	readonly denies: readonly object[];
+};