@lenso/authorization 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,408 @@
-# Temporary Holding Version
+# @lenso/authorization
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A composable authorization engine for trusted application facts. It has no User
+table, required organization, HTTP transport, database, authentication method or
+Lenso runtime dependency. RBAC is one module, not the engine's only model.
+
+| Entry                                                     | Purpose                                                            |
+| --------------------------------------------------------- | ------------------------------------------------------------------ |
+| `@lenso/authorization`                                    | Decisions, conditions, scoped RBAC, bounded lists, role management |
+| `@lenso/authorization/auth`                               | Adapter to one exact existing Auth `Access.enforce` chain          |
+| `@lenso/authorization/plugin`                             | Thin Lenso setup wrapper                                           |
+| `@lenso/authorization/drizzle/pg`                         | Borrowed native Drizzle PostgreSQL role store                      |
+| `@lenso/authorization/drizzle/d1`                         | Borrowed native Drizzle D1 role store                              |
+| `@lenso/authorization/drizzle/sqlite`                     | Borrowed Bun SQLite role store                                     |
+| `@lenso/authorization/drizzle/schema-pg`, `schema-sqlite` | Role graph schemas                                                 |
+| `@lenso/authorization/migrations/*`                       | Explicit SQL migrations                                            |
+
+The root imports none of Auth, Lenso, Drizzle, Manage, Web, Tasks, Log or OTel.
+Optional peers are required only by the selected subpath. No Cedar, OpenFGA or
+Casbin dependency is installed. Relation and custom-policy interfaces allow an
+application-owned external adapter without copying a policy language.
+
+## Trust and evaluation contract
+
+`Principal` identifies `(realmId, subjectId, kind)`. A realm is a verified
+identity-source namespace, not a tenant. Equal emails or subject IDs in different
+realms do not link accounts. Explicit application mapping is required.
+
+The pure core accepts facts already trusted by the caller; it **does not
+authenticate a JSON principal**. Keep it inside the service, after authentication
+and resource loading. Public request DTOs must not supply the principal,
+membership, resource scope/owner, credential ceilings or approval facts.
+
+`Request<Action, Resource, Context>` carries the principal (or explicit `null`),
+action, resource and context. Core facts must be finite plain data; dates should
+be projected to timestamps/strings. Each check copies and freezes facts before
+awaiting callbacks. Callbacks are trusted installed code, not a sandbox.
+
+Evaluation order:
+
+1. Validate the action and required identity, realm, operation audience and
+   credential presence. Missing required facts deny.
+2. Optionally resolve authoritative resource attributes. Its type and ID cannot
+   change; scope comes from this resolved object, not an unverified client claim.
+3. Intersect any verified credential permissions/expiry with the target, optionally
+   resolve trusted attributes, then run all application `boundaries`. No
+   allow-producing extension runs before these.
+4. Evaluate matching rules and installed policies. Policies return exactly
+   `allow`, `deny` or `abstain`. Applicable explicit deny wins; otherwise any
+   allow grants; all abstain/no match denies.
+
+Actions, resource types/IDs, scopes and attribute keys match **exactly**.
+`scope` is `{type,id}`, with no inferred parent, tenant prohibition or wildcard.
+A permission with no `resourceId` explicitly covers every resource of its exact
+type in its exact scope. `*` has no special meaning. A rule with no scope
+explicitly applies across scopes, so use it deliberately.
+
+Independent allow rules/policies are OR grants. Use `all(...)` for an RBAC grant
+AND a resource/request condition; do not install a second allow rule and expect
+it to restrict the first. `any(...)` is explicit OR inside a condition. Both
+require nonempty children; cycles/depth over 32 are rejected. Every evaluated
+branch is checked, so an exception in an OR branch cannot be hidden by true.
+
+Built-in ABAC is limited to own-key primitive `equals`/`in` comparisons on
+principal/resource attributes or context. Missing attributes never match, even
+against `null`. Trusted predicates can express application-specific logic.
+An optional structured `attributes: {resolve(request,evaluation)}` provider
+replaces selected principal/resource attribute bags or context with authoritative
+finite facts. It cannot change identity, action, scope or credential ceilings,
+or mint a principal for an anonymous request. Omitted bags retain supplied facts;
+returned bags replace, not merge. Provider exceptions refuse access.
+Relations make one direct resolver call per relation condition: no graph
+traversal, recursive usersets or relationship database is provided.
+
+Unknown actions/roles, invalid graphs/outcomes, evaluated resolver exceptions and
+timeouts cannot yield allow. Default deadline is 1 second; `timeoutMs` supports
+1–60,000 ms. The deadline races asynchronous evaluation and checks elapsed time
+before allow, but cannot preempt synchronous JavaScript or terminate callback
+work. Callbacks must honor `Evaluation.signal`, remain read-only and settle
+after cancellation. Late callback success cannot change a returned deny.
+
+`check` always returns a safe `{effect,code}`; `can` returns a boolean; `enforce`
+rejects with `AuthorizationError("Access denied.")`. All are asynchronous.
+No resource IDs, exception text or rule data enter decisions. Reason codes are
+service diagnostics, not a public policy-discovery endpoint: untrusted callers
+receive the same generic denial via `enforce`, or a boolean preview via `can`.
+Do not serialize distinct check/error categories, backend counts or lookup errors
+in a way that distinguishes a hidden resource from an absent one.
+
+## Four minimal recipes
+
+These recipes use the existing Notes domain, not a new demo application.
+Executable counterparts are in [test/usage.test.ts](test/usage.test.ts); the
+real Auth adapter uses `StoredNote` from the existing Notes example in
+[test/auth.test.ts](test/auth.test.ts).
+
+### 1. Pure RBAC, without organizations, DB or Lenso
+
+```ts
+import { createAuthorization, rbacPolicy, type RoleGraph } from "@lenso/authorization";
+
+const scope = { type: "personal", id: "home" };
+const principal = { realmId: "notes", subjectId: "alice", kind: "user" };
+const graph: RoleGraph = {
+  roles: [
+    {
+      id: "reader",
+      scope,
+      permissions: [{ action: "read", resourceType: "note", scope }],
+    },
+  ],
+  bindings: [{ id: "alice-reader", principal, roleId: "reader", scope }],
+};
+const authorization = createAuthorization({
+  actions: ["read"],
+  policies: [rbacPolicy({ actions: ["read"], graph })],
+});
+await authorization.enforce({
+  principal,
+  action: "read",
+  context: {},
+  resource: { type: "note", id: "one", scope },
+});
+```
+
+Static graph configuration is detached on construction. For editable roles use
+`memoryRoleStore(graph, actions)` or a persistent store, and pass `store` instead
+of `graph` to RBAC. Roles belong to a scope, not a global string on the user.
+Same-scope `inherits: ["reader"]` is supported. Graphs reject cycles, missing
+parents, cross-scope permissions/parents, duplicate keys and unknown actions.
+Limits are 512 roles, 4,096 bindings and 512 permissions per role.
+
+### 2. RBAC plus resource/request constraints
+
+Replace the standalone RBAC policy with one conjunctive grant:
+
+```ts
+import { all, attribute, predicate, rbacPredicate } from "@lenso/authorization";
+
+const authorization = createAuthorization({
+  actions: ["read"],
+  rules: [
+    {
+      id: "reader-open",
+      effect: "allow",
+      actions: ["read"],
+      resourceType: "note",
+      when: all(
+        predicate(rbacPredicate({ actions: ["read"], graph })),
+        attribute("resource", "state", "equals", "open"),
+      ),
+    },
+  ],
+});
+```
+
+Additional realm/audience, approval or credential limits go in `identity` and
+`boundaries`, not another allow rule. A platform-scoped administrator role is an
+ordinary explicit grant, still subject to all boundaries.
+
+### 3. Organization membership or resource sharing
+
+```ts
+import { any, relation } from "@lenso/authorization";
+
+const organization = {
+  type: "organization",
+  id: "team-a",
+  scope: { type: "platform", id: "my-app" },
+};
+const authorization = createAuthorization({
+  actions: ["read"],
+  relations: applicationRelations, // { check(principal, relation, resource, evaluation) }
+  rules: [
+    {
+      id: "member-or-shared",
+      effect: "allow",
+      actions: ["read"],
+      resourceType: "note",
+      when: any(relation("member", organization), relation("shared-with")),
+    },
+  ],
+});
+```
+
+`applicationRelations` reads verified memberships/shares from the application's
+existing owner. Explicit resource sharing can permit a legitimate cross-org
+operation. If cross-org access needs an approval, require it in a boundary.
+No organization module or table is mandatory.
+
+### 4. Custom policy with a credential ceiling
+
+```ts
+const authorization = createAuthorization({
+  actions: ["read", "write"],
+  identity: { credentialRequired: true },
+  policies: [
+    {
+      evaluate: (facts) => (facts.principal?.kind === "service" ? "allow" : "abstain"),
+    },
+  ],
+});
+await authorization.enforce({
+  principal: verifiedServicePrincipal,
+  action: "read",
+  resource: loadedNoteResource,
+  context: {},
+  credential: verifiedReadOnlyCredentialLimit,
+});
+```
+
+An API key ceiling intersects the current subject's effective permissions; it
+does not create roles, bypass revocation or confer Console admission. Independent
+service principals are evaluated under their own bindings. A custom policy
+cannot bypass a declared credential ceiling. Expiry is checked at the evaluation
+snapshot, not guaranteed through a later business write.
+
+## Existing Auth and Notes service
+
+```ts
+import { createAuthorizedAccess } from "@lenso/authorization/auth";
+
+const protectedRead = createAuthorizedAccess(
+  authentication.for(notesAudiences.read),
+  authorization,
+  ({ resource: note, membership }) => ({
+    resource: {
+      type: "note",
+      id: note.id,
+      scope: { type: "personal", id: note.ownerId },
+      attributes: { owner: note.ownerId },
+    },
+    context: { membership },
+  }),
+);
+// The service loads the actual note, then enforces before returning content.
+await protectedRead.enforce(actor, "read", loadedNote, { signal });
+```
+
+This is the application-owned replacement for that operation's current service
+policy, not an additional route-only check or a parallel authorization truth.
+Every call enters the exact Auth `Access.enforce` chain, revalidates credentials
+and reads configured membership before projecting facts. Actor identity and
+audience only come from its verified callback. Forged/copied actors, another Auth
+instance, wrong audience, revoked credentials and missing membership fail.
+The adapter detaches cloneable business records and membership before async
+projection; `Date` in `StoredNote` is supported, resource handles/functions are
+not. The projected core facts still must be finite plain data.
+
+The current public Auth API does not expose verified API-key scopes. Supply
+`credential` from an application-owned verified ceiling reader in the facts
+callback and set `identity.credentialRequired` when it is mandatory. Do not
+infer scopes from JSON or an actor's kind. Extending Auth's verified source
+contract belongs to its integration owner.
+
+Auth currently refuses null in `Access.enforce`; this adapter therefore protects
+authenticated operations only. An explicitly public anonymous entry may call
+the pure engine with `principal:null` and a public-resource predicate. A failed
+login is not anonymous fallback. Auth still works unchanged when this package
+is not installed. Source/facts callbacks use existing Auth's cooperative signal
+contract; the engine timeout does not bound authentication before its callback.
+
+## Console identity choices
+
+- **Shared realm:** business accounts, org memberships and Console admission
+  remain separate facts. Explicit `console` instance or platform bindings grant
+  admission; org ownership does not. Customer-content read, financial changes and
+  impersonation need separate actions, credential ceilings and approval gates.
+- **Separate Console SSO/realm:** install a different Auth source/instance and
+  audience, then reuse the same core contracts. Map identities only by an explicit
+  trusted application mapping. A matching email/subject ID is not a mapping.
+
+Neither deployment dictates shared or separate `users` tables. Platform grants
+must deliberately express resource scopes or approved cross-scope policy; there
+is no magic global administrator and no `skipAuth`.
+
+## Role administration and optional Manage
+
+Management is **off by default**: no routes, operations or tools are registered.
+Construct `createRoleManagement` only with trusted `authorize` and
+`grantAuthority` adapters. It provides concrete `createRole` (grant),
+`editRole` (edit), `bindRole` (bind), `revokeBinding` (revoke), and
+`delegateRole` (delegate). Using a permission grants none of these actions.
+
+`authorize` receives the scope, target ID and immutable proposed role/binding
+(including recipient and delegation source). It must use a real Auth actor or
+trusted entry credential, compare it to the supplied principal, and run the
+same service-side authorization chain. This is not satisfied by accepting
+`request.actor` JSON or returning true for a claimed role. Application policy can
+forbid self-binding, restrict recipients and require approval for a particular
+proposal. Explicit authorized self-binding is not globally forbidden.
+
+`grantAuthority` supplies the verified `permissions`, exact `scopes` and finite
+`maxExpiresAt`, intersected with the current credential ceiling and any approval.
+All inherited/effective proposed permissions must fit. New bindings require a
+live finite expiry. Role edits also check affected descendants and existing
+binding expiries, including unbound roles that could stage elevation. An editor
+cannot increase their own effective permissions through an already-bound role
+or ancestor. Every accepted mutation validates the complete graph and performs
+one revision CAS; conflicts are not retried.
+
+The graph is read **before** management authorization so revocation/change in
+that same store during authorization loses the final CAS. Authorization from
+another store, credential owner, clock or external approval is not atomically
+fenced by this CAS; stronger operations require a business-owned transaction or
+conditional write at that boundary. Pass a deadline `Evaluation.signal` and a
+fresh trusted `now`; do not retain an Evaluation as a permission ticket.
+
+Delegation creates an independent binding capped at issuance by grant authority,
+source effective permissions and source expiry. Revoking its source later does
+not cascade. Later separately authorized role edits change all active bindings;
+issuance permissions are not a permanent delegated snapshot ceiling. Applications
+requiring cascading or immutable delegation should reject `delegateRole` and
+use a separately reviewed adapter, not assume those guarantees.
+
+Mutation results contain only a revision, never the complete graph. Store reads
+and `effective*` helpers are trusted internal APIs, not management list endpoints;
+validate graphs before using the helper functions directly.
+
+To enable Manage, wrap selected concrete methods in an application service that
+obtains a trusted actor via its existing entry binding. Declare the same shared
+schema/service with `defineOperation`, then use existing `defineManage` with the
+exact plugin and only those operations. CLI, MCP and agent allowlists are separate;
+no business input accepts an actor/grant proof. Reuse Tasks for durable management
+work if needed, but its payload must not persist an allow ticket. No public
+Auth/Tasks/Manage interfaces are modified by this package.
+
+## Lists, snapshots, revocation and write boundaries
+
+Single-object `check` does not authorize a whole query. `authorizeList` implements
+the explicit bounded fallback: pass the **complete** trusted candidate set
+(maximum 1,000), shared request facts and `{maxCandidates,offset,limit}`.
+It checks every item before pagination, returns only visible items and a visible
+total, and refuses oversized sets or any evaluation failure without partial
+results. Do not pass one unrestricted backend page, its count/aggregates, or
+resource-specific errors to callers. Aggregate only over the authorized result.
+
+This release does not compile rules, arbitrary TypeScript predicates or relation
+resolvers into SQL. For unbounded lists, refuse unless the application has an
+independently reviewed equivalent database constraint that includes boundaries,
+denies and current credentials. A candidate-fetch optimization may narrow a
+superset, but does not replace final item checks. UI previews are UX only; Web,
+CLI, MCP and agents call the same protected service.
+
+Store-backed RBAC reads on every evaluation; there is no positive cross-request
+cache. A caller can explicitly read one `RoleSnapshot` and construct request-local
+RBAC with its graph, plus one trusted resource/context snapshot, for repeated
+checks. That snapshot remains stale through the rest of that invocation; discard
+it afterward. Shared snapshots do not create atomicity across separate resolvers.
+
+Revocation is observed by the next fresh read that sees the committed graph
+revision. Existing decisions/in-flight snapshots are not invalidated. Database
+replicas, transaction snapshots and adapter caches can delay it; short TTL is not
+instant revocation. Policy/graph, identity/membership, credential and resource
+versions plus invalidation must be designed before adding a positive cache.
+
+An allow is not a durable capability. Mutable owner/status/balance conditions
+need an atomic recheck or version/owner predicate in the actual business write.
+[test/toctou.test.ts](test/toctou.test.ts) uses real SQLite to demonstrate a
+concurrent owner change making the conditional write affect zero rows.
+DB transactions cannot cover external notifications/payments; their effects need
+their own reviewed idempotency/fencing/compensation. No exactly-once claim is made.
+
+## Explanation, observation and lifecycle
+
+Ordinary `check` has no rule paths. Configure an explicit `explain` action/resource
+gate to enable `explain(managerRequest,targetRequest)`; the manager must be
+authenticated at the trusted entry and pass that gate. Its result contains safe
+reason codes and ordinal paths such as `rules/0/deny`, not rule IDs, tenant IDs,
+predicate details or exception messages. Never expose raw core facts/graphs as
+diagnostics. Auth-backed explanation must run within the application's verified
+management `Access.enforce` callback, not accept a JSON manager request.
+
+Optional `observe` receives only completed policy decision codes/effects, not
+all early identity/error outcomes. It can call existing Log/OTel interfaces;
+observer failure/timeout refuses access. Logging is not durable auditing, and
+this callback provides no atomic audit/write guarantee.
+
+The core owns no connections, workers or timers beyond per-check deadlines.
+Drizzle stores borrow their database and never close it. `createAuthorizationPlugin`
+accepts `setup(context)` and exact `requires` instances; setup obtains providers
+with `context.get(provider)`. Owned resources must register cleanup immediately
+through existing Lenso lifecycle; borrowed Auth/DB instances remain with owners.
+Startup configuration can use existing `definePluginConfig`/`bindConfig`; validated
+engine options are ordinary TypeScript configuration, not a new config center.
+
+## Persistence and checks
+
+See [Drizzle adapter notes](src/drizzle/README.md) for initialization, database
+consistency and migrations. Local checks:
+
+```sh
+bun run --cwd packages/lenso build
+bun run --cwd packages/auth build
+bun run --cwd packages/authorization build
+bun run --cwd packages/authorization typecheck
+bun run --cwd packages/authorization test
+```
+
+The PostgreSQL fixture test is skipped unless an explicitly task-owned local
+`authorization_fixture` database is supplied with `AUTHORIZATION_TEST_PG_URL`
+and `AUTHORIZATION_TEST_PG_OWNED=1`. Never point it at an existing app/production
+database. D1 uses local Miniflare, not a deployed Cloudflare database.
+See [VALIDATION.md](VALIDATION.md) for actual results and remaining unverified items.
+
+Design references consulted: [OWASP authorization](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html),
+[Cedar terminology](https://docs.cedarpolicy.com/overview/terminology.html),
+[OpenFGA concepts](https://openfga.dev/docs/authorization-concepts).

package/VALIDATION.md

@@ -0,0 +1,105 @@
+# Authorization validation
+
+## Initial implementation checks
+
+Validated locally with Bun **1.4.2**, TypeScript **7.0.2**, Drizzle **0.45.3**
+and PostgreSQL **18.6**. Dependencies were restored from local cache with
+`bun install --offline --no-save --ignore-scripts`; `bun.lock` was not changed.
+
+- Built `packages/lenso` and `packages/auth` before using their public exports.
+- `bun run --cwd packages/authorization build`: declaration generation and split
+  Bun build passed.
+- `bun run --cwd packages/authorization typecheck`: passed.
+- `bun run --cwd packages/authorization test`: **64 passed, 1 PostgreSQL test
+  skipped by default, 0 failures** across 12 files.
+- The PostgreSQL test was also run separately against a newly initialized,
+  task-owned loopback PostgreSQL cluster and `authorization_fixture` database:
+  **1 passed, 0 failures**. The cluster was stopped afterward. No existing database
+  was touched.
+- `oxlint packages/authorization --deny-warnings`, package-only `oxfmt --check`,
+  and `git diff --check`: passed.
+- `bun pm pack --ignore-scripts` produced a local artifact containing declarations,
+  split JS chunks, migrations and documentation. In a scratch consumer with none
+  of Auth/core/Drizzle/Manage installed, the packed root imported and performed
+  actual RBAC allow/deny checks.
+- All eight declared public JavaScript entry points loaded through package exports
+  with their selected workspace peers installed. Nothing was published.
+- Final independent source review covered core/attribute ordering, Auth provenance
+  and snapshots, management grant/edit/delegation, RBAC/list handling, persistent
+  graph validation/CAS and optional dependency boundaries. It found no additional
+  source-backed blockers under the documented trust model. This review did not
+  independently execute tests, generated declarations or packed consumers.
+
+The PostgreSQL command used the test's exact opt-in variables
+`AUTHORIZATION_TEST_PG_URL` (task-owned loopback URL) and
+`AUTHORIZATION_TEST_PG_OWNED=1`, then ran
+`bun test packages/authorization/test/pg.test.ts`. No production connection,
+credential, notification, charge, deployment or publication was used.
+
+## Behavior covered
+
+- Full allow/deny/abstain conflict matrix in both orders; matching explicit deny
+  precedence; default denial; exact scope/action/resource matching.
+- AND narrowing versus explicit OR; missing attributes; direct relationships;
+  anonymous public resources; explicit approved cross-org access and refusal.
+- Credential presence, expiry and permission intersection before custom grants.
+- Real existing Auth provenance checks for copied/JSON/foreign actors, wrong
+  audience, source revocation and membership loss; source/facts exception safety.
+- Auth resource/membership snapshots across controlled asynchronous races.
+- Independent management actions, bounded grant scopes/resources/expiry,
+  inherited and staged role-edit elevation, malformed/cyclic role graphs,
+  recipient-aware authorization and JSON-principal refusal through real Auth.
+- Current-store revocation and concurrent revision conflicts, including
+  revocation while a management authorizer is paused.
+- Lists checked before pagination, visible-only total, bounded fallback refusal
+  and no partial result on evaluated failures.
+- Timeout, abort, malformed policy outputs, resolver errors and late success;
+  explanation gate with ordinal paths and safe denial messages.
+- Real SQLite owner/version conditional update after a concurrent owner change.
+- Actual SQLite migration/driver, JSON corruption, namespace isolation, immutable
+  snapshots, unchanged/stale revision refusal and one conditional-write winner.
+- Local **Miniflare D1** migration and real Drizzle D1 driver, `UPDATE RETURNING`,
+  concurrent CAS and invalid graph rejection. This is an emulator check, not a
+  Cloudflare deployment.
+- Actual PostgreSQL migration/Bun SQL JSONB roundtrip, namespaces, immutable read,
+  revocation document update, concurrent CAS and malformed graph rejection.
+- Lenso exact instance dependencies, borrowed resource ownership and existing
+  Config binding. Four minimal executable recipes reuse the Notes domain.
+
+## Landing integration
+
+The landing integration, explicitly authorized by the user, registers this
+workspace and its dependencies in the shared `bun.lock`. The resulting
+`bun install --frozen-lockfile` passed without further lockfile changes.
+`scripts/ci-checks.sh` creates an additional task-owned `authorization_fixture`
+database in its own temporary cluster and explicitly runs this package's
+PostgreSQL test, rather than treating its default skip as backend validation.
+Ambient Authorization test connection/ownership variables are cleared first.
+The integration also records the public package change through Changesets;
+no package versioning or registry publication is performed by this landing.
+
+## Deliberate limits and unverified items
+
+- The initial implementation did not run the whole-repository pipeline or a live
+  Web/CLI/MCP/Manage deployment. No transport operations were auto-registered.
+- Public Auth does not expose verified API-key scopes; application-owned verified
+  ceiling readers are required. Anonymous Auth `enforce` is not available; an
+  explicit public pure-core entry is documented instead.
+- No external SSO, policy/relationship provider, deployed D1, replica-lag/failover,
+  other PostgreSQL version or other platform certification was tested.
+- No SQL compiler is provided. Lists use a complete bounded candidate set or
+  must refuse pending an independently reviewed application constraint.
+- No positive cross-request cache or invalidation protocol is provided. Revocation
+  takes effect when a fresh authoritative read sees the committed revision;
+  old decisions and in-flight snapshots remain old.
+- Whole-graph CAS fences changes in the same role store. It does not atomically
+  fence separate Auth/membership/credential/resource stores, time expiry, approval
+  owners or external side effects. Business writes must recheck/fence their own
+  mutable state.
+- Delegation creates independent bindings, with no cascading revocation or
+  permanent issuance-permission snapshot through later authorized role edits.
+- Timers cannot preempt synchronous JS or forcibly settle providers. Async
+  callbacks must cooperate with cancellation. A cancelled committed mutation
+  can leave an uncertain caller outcome; it is not automatically retried.
+- Optional observation is not a durable audit store or an atomic audit/write
+  transaction. No strict global consistency or exactly-once guarantee is claimed.

package/dist/auth.d.ts

@@ -0,0 +1,22 @@
+import { type Access, type Actor, type PolicyContext } from "@lenso/auth";
+import type { Attributes, Awaitable, Authorization, CredentialLimit, Decision, Resource } from "./types";
+export interface AuthorizationFacts<A extends string, R extends Resource, C> {
+    readonly resource: R;
+    readonly context: C;
+    readonly attributes?: Attributes;
+    /** Independently verified credential ceiling. Never read from business JSON. */
+    readonly credential?: CredentialLimit<A>;
+}
+export interface AuthorizedAccess<P, A extends string, T> {
+    check(actor: P | null, action: A, resource: T, options?: {
+        signal?: AbortSignal;
+    }): Promise<Decision>;
+    can(actor: P | null, action: A, resource: T, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    enforce(actor: P | null, action: A, resource: T, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** Every call reuses the exact Access.enforce chain; this is not another authenticator. */
+export declare function createAuthorizedAccess<Realm extends string, E, S extends string, Audience extends string, T, M, A extends string, R extends Resource, C>(access: Access<Realm, E, S, Audience, T, M>, authorization: Authorization<A, R, C>, facts: (verified: PolicyContext<Actor<Realm, S, Audience>, T, M>) => Awaitable<AuthorizationFacts<A, R, C>>): AuthorizedAccess<Actor<Realm, S, Audience>, A, T>;

package/dist/auth.js

@@ -0,0 +1,59 @@
+import {
+  AuthorizationError2
+} from "./index-6f5nrdh9.js";
+
+// src/auth.ts
+import { AuthError } from "@lenso/auth";
+function createAuthorizedAccess(access, authorization, facts) {
+  const check = async (actor, action, resource, options) => {
+    let decision;
+    try {
+      const invocationResource = structuredClone(resource);
+      await access.enforce(actor, invocationResource, async (verified) => {
+        const trusted = await facts(Object.freeze({
+          ...verified,
+          membership: structuredClone(verified.membership)
+        }));
+        decision = await authorization.check({
+          principal: {
+            realmId: verified.principal.realmId,
+            subjectId: verified.principal.subjectId,
+            kind: verified.principal.kind,
+            ...trusted.attributes ? { attributes: trusted.attributes } : {}
+          },
+          action,
+          resource: trusted.resource,
+          context: trusted.context,
+          audience: verified.principal.audience,
+          ...trusted.credential ? { credential: trusted.credential } : {}
+        }, { signal: verified.signal });
+        return decision.effect === "allow";
+      }, options);
+      return decision ?? Object.freeze({ effect: "deny", code: "EVALUATION_FAILED" });
+    } catch (error) {
+      if (error instanceof AuthError) {
+        if (error.code === "FORBIDDEN" && decision?.effect === "deny")
+          return decision;
+        if (error.code === "UNAUTHORIZED" || error.code === "REAUTHENTICATION_REQUIRED")
+          return Object.freeze({ effect: "deny", code: "BOUNDARY_DENIED" });
+      }
+      return Object.freeze({
+        effect: "deny",
+        code: options?.signal?.aborted ? "CANCELLED" : "EVALUATION_FAILED"
+      });
+    }
+  };
+  return Object.freeze({
+    check,
+    async can(...args) {
+      return (await check(...args)).effect === "allow";
+    },
+    async enforce(...args) {
+      if ((await check(...args)).effect !== "allow")
+        throw new AuthorizationError2;
+    }
+  });
+}
+export {
+  createAuthorizedAccess
+};

package/dist/conditions.d.ts

@@ -0,0 +1,8 @@
+import type { Attributes, Condition, Predicate, Resource, Scope, Permission, Request } from "./types";
+export declare function all<A extends string = string, R extends Resource = Resource, C = Attributes>(...conditions: readonly Condition<A, R, C>[]): Condition<A, R, C>;
+export declare function any<A extends string = string, R extends Resource = Resource, C = Attributes>(...conditions: readonly Condition<A, R, C>[]): Condition<A, R, C>;
+export declare function predicate<A extends string = string, R extends Resource = Resource, C = Attributes>(test: Predicate<A, R, C>): Condition<A, R, C>;
+export declare function attribute(source: "principal" | "resource" | "context", key: string, operator: "equals" | "in", value: string | number | boolean | null | readonly (string | number | boolean | null)[]): Condition;
+export declare function relation(name: string, target?: Resource): Condition;
+export declare function sameScope(left: Scope, right: Scope): boolean;
+export declare function matchesPermission(permission: Permission, request: Request<string, Resource, unknown>): boolean;

package/dist/core.d.ts

@@ -0,0 +1,2 @@
+import type { Attributes, Authorization, AuthorizationOptions, Resource } from "./types";
+export declare function createAuthorization<A extends string = string, R extends Resource = Resource, C = Attributes>(options: AuthorizationOptions<A, R, C>): Authorization<A, R, C>;

package/dist/drizzle/d1.d.ts

@@ -0,0 +1,4 @@
+import type { DrizzleD1Database } from "drizzle-orm/d1";
+export declare function d1RoleStore<A extends string = string, TSchema extends Record<string, unknown> = Record<string, unknown>>(db: DrizzleD1Database<TSchema>, namespace: string, actions: readonly A[]): import("..").RoleStore<A> & {
+    initialize(snapshot: import("..").RoleSnapshot<A>): Promise<void>;
+};

package/dist/drizzle/d1.js

@@ -0,0 +1,12 @@
+import"../index-qjqy8v4k.js";
+import {
+  sqliteStore2
+} from "../index-pmwmdjss.js";
+
+// src/drizzle/d1.ts
+function d1RoleStore(db, namespace, actions) {
+  return sqliteStore2(db, namespace, actions);
+}
+export {
+  d1RoleStore
+};

package/dist/drizzle/pg.d.ts

@@ -0,0 +1,5 @@
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import type { RoleSnapshot, RoleStore } from "../types";
+export declare function postgresRoleStore<A extends string = string, TSchema extends Record<string, unknown> = Record<string, unknown>, TResult extends PgQueryResultHKT = PgQueryResultHKT>(db: PgDatabase<TResult, TSchema>, namespace: string, actions: readonly A[]): RoleStore<A> & {
+    initialize(snapshot: RoleSnapshot<A>): Promise<void>;
+};