@lenso/authorization 0.0.0-stage → 0.2.1

package/dist/types.d.ts

@@ -0,0 +1,162 @@
+export type Awaitable<T> = T | Promise<T>;
+export type Attributes = Readonly<Record<string, unknown>>;
+/** Trusted application facts, not a credential or an authenticated JSON DTO. */
+export interface Principal {
+    readonly realmId: string;
+    readonly subjectId: string;
+    readonly kind: string;
+    readonly attributes?: Attributes;
+}
+export interface Scope {
+    readonly type: string;
+    readonly id: string;
+}
+export interface Resource {
+    readonly type: string;
+    readonly id: string;
+    readonly scope: Scope;
+    readonly attributes?: Attributes;
+}
+export interface Permission<A extends string = string> {
+    readonly action: A;
+    readonly resourceType: string;
+    readonly scope: Scope;
+    /** Omission explicitly means every resource of this type in the exact scope. */
+    readonly resourceId?: string;
+}
+export interface CredentialLimit<A extends string = string> {
+    readonly permissions: readonly Permission<A>[];
+    readonly expiresAt?: number;
+}
+export interface Request<A extends string = string, R extends Resource = Resource, C = Attributes> {
+    readonly principal: Principal | null;
+    readonly action: A;
+    readonly resource: R;
+    readonly context: C;
+    readonly audience?: string;
+    readonly credential?: CredentialLimit<A>;
+}
+export type Effect = "allow" | "deny" | "abstain";
+export type ReasonCode = "ALLOWED" | "DEFAULT_DENY" | "EXPLICIT_DENY" | "BOUNDARY_DENIED" | "UNKNOWN_ACTION" | "EVALUATION_FAILED" | "TIMEOUT" | "CANCELLED";
+export interface Decision {
+    readonly effect: "allow" | "deny";
+    readonly code: ReasonCode;
+}
+export interface Evaluation {
+    readonly signal: AbortSignal;
+    readonly now: number;
+}
+export type Predicate<A extends string = string, R extends Resource = Resource, C = Attributes> = (request: Request<A, R, C>, evaluation: Evaluation) => Awaitable<boolean>;
+export type Condition<A extends string = string, R extends Resource = Resource, C = Attributes> = {
+    readonly kind: "all";
+    readonly conditions: readonly Condition<A, R, C>[];
+} | {
+    readonly kind: "any";
+    readonly conditions: readonly Condition<A, R, C>[];
+} | {
+    readonly kind: "predicate";
+    readonly test: Predicate<A, R, C>;
+} | {
+    readonly kind: "attribute";
+    readonly source: "principal" | "resource" | "context";
+    readonly key: string;
+    readonly operator: "equals" | "in";
+    readonly value: string | number | boolean | null | readonly (string | number | boolean | null)[];
+} | {
+    readonly kind: "relation";
+    readonly relation: string;
+    readonly target?: Resource;
+};
+export interface Rule<A extends string = string, R extends Resource = Resource, C = Attributes> {
+    /** Local identifier; explanations return ordinal paths, never this value. */
+    readonly id: string;
+    readonly effect: "allow" | "deny";
+    readonly actions: readonly A[];
+    readonly resourceType: string;
+    readonly scope?: Scope;
+    readonly resourceId?: string;
+    readonly when: Condition<A, R, C>;
+}
+export interface Policy<A extends string = string, R extends Resource = Resource, C = Attributes> {
+    evaluate(request: Request<A, R, C>, evaluation: Evaluation): Awaitable<Effect>;
+}
+export interface RelationResolver {
+    check(principal: Principal, relation: string, resource: Resource, evaluation: Evaluation): Awaitable<boolean>;
+}
+export interface ResolvedAttributes<C = Attributes> {
+    readonly principal?: Attributes;
+    readonly resource?: Attributes;
+    readonly context?: C;
+}
+export interface AttributeResolver<A extends string = string, R extends Resource = Resource, C = Attributes> {
+    resolve(request: Request<A, R, C>, evaluation: Evaluation): Awaitable<ResolvedAttributes<C>>;
+}
+export interface AuthorizationOptions<A extends string, R extends Resource, C> {
+    readonly actions: readonly A[];
+    readonly rules?: readonly Rule<A, R, C>[];
+    readonly policies?: readonly Policy<A, R, C>[];
+    /** These intersect before any allow-producing extension executes. */
+    readonly boundaries?: readonly Predicate<A, R, C>[];
+    readonly identity?: {
+        readonly required?: boolean;
+        readonly realms?: readonly string[];
+        readonly audiences?: readonly string[];
+        readonly credentialRequired?: boolean;
+    };
+    readonly relations?: RelationResolver;
+    readonly attributes?: AttributeResolver<A, R, C>;
+    readonly resolveResource?: (resource: R, evaluation: Evaluation) => Awaitable<R>;
+    readonly timeoutMs?: number;
+    readonly clock?: () => number;
+    /** No subject, resource IDs, policy data or exception messages are supplied. */
+    readonly observe?: (decision: Decision) => Awaitable<void>;
+    readonly explain?: {
+        readonly action: A;
+        readonly resource: R;
+    };
+}
+export interface Explanation {
+    readonly decision: Decision;
+    readonly paths: readonly string[];
+}
+export interface Authorization<A extends string = string, R extends Resource = Resource, C = Attributes> {
+    check(request: Request<A, R, C>, options?: {
+        signal?: AbortSignal;
+    }): Promise<Decision>;
+    can(request: Request<A, R, C>, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    enforce(request: Request<A, R, C>, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    explain(manager: Request<A, R, C>, target: Request<A, R, C>, options?: {
+        signal?: AbortSignal;
+    }): Promise<Explanation>;
+}
+export interface Role<A extends string = string> {
+    readonly id: string;
+    readonly scope: Scope;
+    readonly permissions: readonly Permission<A>[];
+    /** IDs resolve only within this role's exact scope. */
+    readonly inherits?: readonly string[];
+}
+export interface Binding {
+    readonly id: string;
+    readonly principal: Principal;
+    readonly roleId: string;
+    readonly scope: Scope;
+    readonly expiresAt?: number;
+}
+export interface RoleGraph<A extends string = string> {
+    readonly roles: readonly Role<A>[];
+    readonly bindings: readonly Binding[];
+}
+export interface RoleSnapshot<A extends string = string> {
+    readonly revision: string;
+    readonly graph: RoleGraph<A>;
+}
+/** Trusted internal repository. Mutations belong behind the authorized management service. */
+export interface RoleStore<A extends string = string> {
+    read(evaluation: Evaluation): Awaitable<RoleSnapshot<A>>;
+    compareAndSwap(expectedRevision: string, next: RoleSnapshot<A>, evaluation: Evaluation): Awaitable<boolean>;
+}

package/migrations/0001-role-graphs-pg.sql

@@ -0,0 +1,5 @@
+CREATE TABLE IF NOT EXISTS authorization_role_graphs (
+  namespace text PRIMARY KEY,
+  revision text NOT NULL,
+  graph jsonb NOT NULL
+);

package/migrations/0001-role-graphs-sqlite.sql

@@ -0,0 +1,5 @@
+CREATE TABLE IF NOT EXISTS authorization_role_graphs (
+  namespace TEXT PRIMARY KEY,
+  revision TEXT NOT NULL,
+  graph TEXT NOT NULL
+);

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@lenso/authorization",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LioRael/lenso.git",
+    "directory": "packages/authorization"
+  },
+  "files": [
+    "dist",
+    "migrations",
+    "README.md",
+    "VALIDATION.md",
+    "src/drizzle/README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "default": "./dist/auth.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./drizzle/pg": {
+      "types": "./dist/drizzle/pg.d.ts",
+      "default": "./dist/drizzle/pg.js"
+    },
+    "./drizzle/d1": {
+      "types": "./dist/drizzle/d1.d.ts",
+      "default": "./dist/drizzle/d1.js"
+    },
+    "./drizzle/sqlite": {
+      "types": "./dist/drizzle/sqlite.d.ts",
+      "default": "./dist/drizzle/sqlite.js"
+    },
+    "./drizzle/schema-pg": {
+      "types": "./dist/drizzle/schema-pg.d.ts",
+      "default": "./dist/drizzle/schema-pg.js"
+    },
+    "./drizzle/schema-sqlite": {
+      "types": "./dist/drizzle/schema-sqlite.d.ts",
+      "default": "./dist/drizzle/schema-sqlite.js"
+    },
+    "./migrations/*": "./migrations/*"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && bun build src/index.ts src/auth.ts src/plugin.ts src/drizzle/pg.ts src/drizzle/d1.ts src/drizzle/sqlite.ts src/drizzle/schema-pg.ts src/drizzle/schema-sqlite.ts --root src --outdir dist --target browser --packages external --splitting",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test test"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "5.20261008.1",
+    "@lenso/auth": "^0.3.1",
+    "@lenso/core": "^0.3.0",
+    "@standard-schema/spec": "1.1.0",
+    "drizzle-orm": "0.45.3",
+    "miniflare": "5.20261006.0-alpha"
+  },
+  "peerDependencies": {
+    "@lenso/auth": "^0.3.1",
+    "@lenso/core": "^0.3.0",
+    "drizzle-orm": "^0.45.3"
+  },
+  "peerDependenciesMeta": {
+    "@lenso/auth": {
+      "optional": true
+    },
+    "@lenso/core": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    }
+  }
+}

package/src/drizzle/README.md

@@ -0,0 +1,48 @@
+# Drizzle role stores
+
+`postgresRoleStore(db, namespace, actions)`, `d1RoleStore(db, namespace, actions)`
+and `sqliteRoleStore(db, namespace, actions)` borrow the supplied native Drizzle
+database. Reads and writes use the same core role-graph validation, including
+known actions, inheritance and scoped bindings; returned snapshots are immutable.
+
+Apply `migrations/0001-role-graphs-pg.sql` or
+`migrations/0001-role-graphs-sqlite.sql` through your explicit migration owner,
+then call `store.initialize(snapshot)` once using trusted bootstrap configuration.
+This is an internal seed API, not an unauthenticated management operation.
+An existing namespace is preserved. Construction and setup run no migration or
+initialization. PostgreSQL JSON is explicitly bound as text and cast to JSONB to
+match the repository's Bun SQL/Drizzle serialization pattern.
+
+Each namespace is stored as one graph document. Compare-and-swap is a single
+conditional `UPDATE ... WHERE namespace = ? AND revision = ? RETURNING ...`.
+It does not wrap authorization data and resource facts in a transaction.
+
+All writers must use a new, never-reused revision token; management generates a
+UUID for every mutation. Reusing the current revision is rejected. Raw store
+access is trusted infrastructure, not an API for clients to choose revisions.
+One graph document makes a role/binding update indivisible within that row,
+but serializes writes in the namespace and is bounded to the core's graph limits.
+It is not a scalable relationship database.
+
+PostgreSQL supports transactions, but this adapter needs only one conditional
+statement. D1 uses the same SQLite statement and no interactive transaction.
+SQLite and local Miniflare exercise `UPDATE RETURNING` with the actual driver.
+Cancellation is checked before and after read/CAS. Cancellation or connection
+loss after commit can leave a successful mutation with an uncertain caller
+outcome: no rollback or automatic retry is promised.
+
+The borrowed database controls consistency. PostgreSQL repeatable-read
+transactions/replicas can retain older snapshots. D1's direct binding queries
+use primary routing per the current docs; an injected D1 Sessions API/replica
+client must be configured for the application's revocation requirement.
+`first-unconstrained` can begin stale; use a fresh `first-primary` session where
+latest primary data is required. The adapter does not infer or override routing.
+
+The update/returning pattern follows Drizzle's
+[PostgreSQL](https://orm.drizzle.team/docs/update) and
+[SQLite](https://orm.drizzle.team/docs/sqlite/update) update APIs. D1 uses
+SQLite-compatible SQL through Drizzle's D1 driver; its prepared statement API
+documents SQLite binding semantics and result retrieval at
+[Cloudflare D1](https://developers.cloudflare.com/d1/worker-api/prepared-statements/).
+Replication/consistency reference:
+[D1 global read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/).