@elytracms/core 0.0.6

package/dist/operations/authorization.d.ts

@@ -0,0 +1,49 @@
+import type { MembersRepository } from '@elytracms/core/persistence';
+import type { AuthorizationHook } from './core';
+/**
+ * Role-based authorization for the operations chokepoint (EC-150, vision AD-7).
+ *
+ * One hook, no UI-scattered checks: every command and query passes through
+ * `createRoleAuthorization` before it may touch the persistence adapter.
+ * Project scope is derived from the operation input — every project-scoped
+ * input schema in this layer carries a `projectId` field — and checked against
+ * the actor's membership for *that* project.
+ *
+ * Role rules (per project):
+ *
+ * | Operation                                        | viewer | editor | admin |
+ * | ------------------------------------------------ | ------ | ------ | ----- |
+ * | queries (`*.get`, `*.list`, …)                   | ✓      | ✓      | ✓     |
+ * | content commands (documents/graph/assets/schema/ |        |        |       |
+ * |   publishing/registry/references)                | ✗      | ✓      | ✓     |
+ * | members.set / members.remove                     | ✗      | ✗      | ✓     |
+ * | tokens.issue / tokens.revoke / tokens.list       | ✗      | ✗      | ✓     |
+ *
+ * Operations *without* a `projectId` get these documented rules:
+ * - Deployment-admin operations (CLI tokens — EC-182) carry no per-project scope
+ *   in single-tenant deployments; they are checked against the actor's
+ *   deployment membership (their role on this one-project deployment).
+ * - Other queries without a project scope are allowed for any authenticated
+ *   principal.
+ * - Any other command without a `projectId` is denied (defensive default).
+ *
+ * Global flags on `Principal.roles`:
+ * - `system` bypasses all checks (seeding, internal tooling — never a browser
+ *   session).
+ *
+ * No actor at all means every operation is denied — unauthenticated sessions
+ * never reach an operation surface (the studio's route guard redirects them),
+ * and non-studio consumers (CLI, AI changesets) must supply a principal.
+ */
+/** Principal flag that bypasses all role checks (internal tooling only). */
+export declare const GLOBAL_SYSTEM_FLAG = "system";
+/** Project lifecycle + administration commands an `editor` may NOT run. */
+export declare const ADMIN_ONLY_OPERATIONS: ReadonlySet<string>;
+/** Extract the project scope from a validated operation input, if present. */
+export declare function projectIdFromInput(input: unknown): string | undefined;
+/**
+ * Build the role-checking {@link AuthorizationHook} over a members repository.
+ * Decisions are structured denials — the pipeline maps them onto the
+ * `unauthorized` {@link OperationError}, which surfaces (EC-141) render verbatim.
+ */
+export declare function createRoleAuthorization(members: MembersRepository): AuthorizationHook;

package/dist/operations/authorization.js

@@ -0,0 +1,128 @@
+import { roleAtLeast } from '@elytracms/core/persistence';
+/**
+ * Role-based authorization for the operations chokepoint (EC-150, vision AD-7).
+ *
+ * One hook, no UI-scattered checks: every command and query passes through
+ * `createRoleAuthorization` before it may touch the persistence adapter.
+ * Project scope is derived from the operation input — every project-scoped
+ * input schema in this layer carries a `projectId` field — and checked against
+ * the actor's membership for *that* project.
+ *
+ * Role rules (per project):
+ *
+ * | Operation                                        | viewer | editor | admin |
+ * | ------------------------------------------------ | ------ | ------ | ----- |
+ * | queries (`*.get`, `*.list`, …)                   | ✓      | ✓      | ✓     |
+ * | content commands (documents/graph/assets/schema/ |        |        |       |
+ * |   publishing/registry/references)                | ✗      | ✓      | ✓     |
+ * | members.set / members.remove                     | ✗      | ✗      | ✓     |
+ * | tokens.issue / tokens.revoke / tokens.list       | ✗      | ✗      | ✓     |
+ *
+ * Operations *without* a `projectId` get these documented rules:
+ * - Deployment-admin operations (CLI tokens — EC-182) carry no per-project scope
+ *   in single-tenant deployments; they are checked against the actor's
+ *   deployment membership (their role on this one-project deployment).
+ * - Other queries without a project scope are allowed for any authenticated
+ *   principal.
+ * - Any other command without a `projectId` is denied (defensive default).
+ *
+ * Global flags on `Principal.roles`:
+ * - `system` bypasses all checks (seeding, internal tooling — never a browser
+ *   session).
+ *
+ * No actor at all means every operation is denied — unauthenticated sessions
+ * never reach an operation surface (the studio's route guard redirects them),
+ * and non-studio consumers (CLI, AI changesets) must supply a principal.
+ */
+/** Principal flag that bypasses all role checks (internal tooling only). */
+export const GLOBAL_SYSTEM_FLAG = 'system';
+/** Project lifecycle + administration commands an `editor` may NOT run. */
+export const ADMIN_ONLY_OPERATIONS = new Set([
+    'members.set',
+    'members.remove',
+    'tokens.issue',
+    'tokens.revoke',
+    // Token *listing* is admin-only too: hashes are never returned, but token
+    // metadata is an administration concern, not a content concern.
+    'tokens.list',
+]);
+/**
+ * Deployment-scoped administration ops (EC-182): single-tenant means a CLI token
+ * needs no per-project scope, so these operations carry no `projectId`. They are
+ * authorized against the actor's membership on this one-project deployment.
+ */
+const DEPLOYMENT_ADMIN_OPERATIONS = new Set([
+    'tokens.issue',
+    'tokens.revoke',
+    'tokens.list',
+]);
+/** Extract the project scope from a validated operation input, if present. */
+export function projectIdFromInput(input) {
+    if (typeof input !== 'object' || input === null)
+        return undefined;
+    const value = input.projectId;
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function deny(reason) {
+    return { allow: false, reason };
+}
+/** The strongest of the actor's roles (single-tenant: typically just one). */
+function highestRole(roles) {
+    let best;
+    for (const role of roles) {
+        if (!best || roleAtLeast(role, best))
+            best = role;
+    }
+    return best;
+}
+const ALLOW = { allow: true };
+/**
+ * Build the role-checking {@link AuthorizationHook} over a members repository.
+ * Decisions are structured denials — the pipeline maps them onto the
+ * `unauthorized` {@link OperationError}, which surfaces (EC-141) render verbatim.
+ */
+export function createRoleAuthorization(members) {
+    return async (context) => {
+        const actor = context.actor;
+        if (!actor) {
+            return deny(`Operation “${context.operation}” requires an authenticated user.`);
+        }
+        const flags = actor.roles ?? [];
+        if (flags.includes(GLOBAL_SYSTEM_FLAG))
+            return ALLOW;
+        const projectId = projectIdFromInput(context.input);
+        if (!projectId) {
+            // Deployment-admin ops (CLI tokens) are scopeless in single-tenant; check
+            // the actor's deployment membership rather than a per-project one.
+            if (DEPLOYMENT_ADMIN_OPERATIONS.has(context.operation)) {
+                const memberships = await members.listMembershipsForUser(actor.id);
+                const role = highestRole(memberships.map((m) => m.role));
+                if (!role) {
+                    return deny(`You are not a member of this deployment.`);
+                }
+                return decideForRole(role, context);
+            }
+            if (context.kind === 'query')
+                return ALLOW;
+            return deny(`Command “${context.operation}” carries no project scope and was denied.`);
+        }
+        const membership = await members.findMember(projectId, actor.id);
+        if (!membership) {
+            return deny(`You are not a member of project “${projectId}”.`);
+        }
+        return decideForRole(membership.role, context);
+    };
+}
+function decideForRole(role, context) {
+    if (ADMIN_ONLY_OPERATIONS.has(context.operation)) {
+        return roleAtLeast(role, 'admin')
+            ? ALLOW
+            : deny(`Operation “${context.operation}” requires the “admin” role (you are “${role}”).`);
+    }
+    if (context.kind === 'query')
+        return ALLOW;
+    return roleAtLeast(role, 'editor')
+        ? ALLOW
+        : deny(`Viewers cannot run commands — “${context.operation}” requires the “editor” role.`);
+}
+//# sourceMappingURL=authorization.js.map

package/dist/operations/authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../../src/operations/authorization.ts"],"names":[],"mappings":"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"}

package/dist/operations/changesets.d.ts

@@ -0,0 +1,160 @@
+import type { PersistenceAdapter } from '@elytracms/core/persistence';
+import { OperationEventBus } from './core';
+import type { AnyOperationDefinition, AuthorizationHook, OperationResult, Principal } from './core';
+/**
+ * Changesets (EC-140, vision AD-7): a batch of operation invocations that can be
+ * **previewed** (structured diff + validation issues, zero side effects),
+ * **applied atomically** (all-or-nothing via compensation), and **reverted**
+ * (inverse operations recorded at apply time). "Review before apply" and undo
+ * are the same primitive, shared by the UI, AI proposals, and automation.
+ *
+ * ## Preview design (dry run with zero mutation)
+ *
+ * Preview executes the changeset's steps — through the real operation pipeline —
+ * against a **scratch `InMemoryPersistenceAdapter` seeded from read-only reads**
+ * of the live adapter (only the entities the steps touch: graph, CMS schema +
+ * documents, manifest records). This was chosen over
+ * re-implementing per-operation domain checks because:
+ *
+ * - the diff you preview is computed by the exact code that will apply,
+ * - later steps see earlier steps' effects (a step may create the collection a
+ *   following step inserts a document into), and
+ * - the live adapter is never handed a single write.
+ *
+ * ## Atomic apply (compensation)
+ *
+ * The persistence boundary has no transactions, so apply records **inverse
+ * invocations** as it goes: before each step it snapshots the touched entity,
+ * executes the step through the real pipeline (validate → authorize → mutate →
+ * event), and derives the operations that would undo it. If a step fails, the
+ * already-applied steps are rolled back in reverse order and a structured error
+ * is returned — state after a failed apply equals state before. On success the
+ * accumulated inverse list (already in reverse order) is kept on the changeset;
+ * `revert` executes it. Rollback and revert run with a pass-through
+ * authorization hook: compensation restores state the actor was already
+ * authorized to change.
+ *
+ * Known inverse approximations (surfaced as warnings at preview time):
+ * - graph revisions are append-only — reverting a graph step saves the prior
+ *   graph as a *new* revision; a changeset that created the very first revision
+ *   cannot be reverted (its inverse is empty).
+ * - reverting a schema step for a project that had no schema record restores an
+ *   *empty* schema record rather than "no record".
+ */
+export type ChangesetState = 'draft' | 'previewed' | 'applied' | 'reverted';
+export type ChangesetSeverity = 'error' | 'warning';
+/**
+ * A validation issue attached to a changeset. The shared issue model: AI
+ * proposal issues (EC-095) are these. Any `error`-severity issue blocks apply.
+ */
+export interface ChangesetIssue {
+    readonly severity: ChangesetSeverity;
+    readonly message: string;
+    readonly code?: string;
+    /** 0-based index of the step the issue belongs to; absent for changeset-level issues. */
+    readonly step?: number;
+}
+/** A single operation invocation inside a changeset (EC-139 dotted name + raw input). */
+export interface ChangesetInvocation {
+    readonly operation: string;
+    readonly input: unknown;
+}
+export type ChangeKind = 'create' | 'update' | 'delete';
+/** One entity touched by one step: identity plus before/after snapshots. */
+export interface ChangesetDiffEntry {
+    /** 0-based index of the step that produces this change. */
+    readonly step: number;
+    readonly operation: string;
+    /** Entity kind, e.g. 'graph' | 'cms-schema' | 'cms-document'. */
+    readonly entity: string;
+    /** Entity identity, e.g. 'prj-1/post/p1'. */
+    readonly key: string;
+    readonly change: ChangeKind;
+    /** Snapshot before the step (absent on create). JSON-shaped data. */
+    readonly before?: unknown;
+    /** Snapshot after the step (absent on delete). JSON-shaped data. */
+    readonly after?: unknown;
+}
+export interface ChangesetPreview {
+    readonly diff: readonly ChangesetDiffEntry[];
+    readonly issues: readonly ChangesetIssue[];
+    /** True when no `error`-severity issue exists — apply is blocked otherwise. */
+    readonly applicable: boolean;
+}
+/** What a caller (AI proposal, studio flow, automation) provides to create a changeset. */
+export interface ChangesetInput {
+    readonly title: string;
+    readonly summary?: string;
+    readonly steps: readonly ChangesetInvocation[];
+    /**
+     * Authoring-time issues (e.g. AI generation validation), merged into every
+     * preview. Error severity blocks apply — preserves the EC-095 contract.
+     */
+    readonly issues?: readonly ChangesetIssue[];
+}
+export interface Changeset {
+    readonly id: string;
+    readonly title: string;
+    readonly summary?: string;
+    readonly steps: readonly ChangesetInvocation[];
+    /** Authoring-time issues carried from {@link ChangesetInput.issues}. */
+    readonly issues: readonly ChangesetIssue[];
+    readonly state: ChangesetState;
+    /** Result of the most recent preview (also computed internally by apply). */
+    readonly preview?: ChangesetPreview;
+    /** Inverse invocations recorded at apply time, already in execution (reverse) order. */
+    readonly inverse?: readonly ChangesetInvocation[];
+}
+/** Which state the scratch preview adapter must be seeded with. */
+type ScratchSeed = 'graph' | 'cms';
+/**
+ * Existential support entry (mirrors `AnyOperationDefinition`): `never`-typed
+ * parameters make every concretely-typed entry assignable.
+ */
+export interface ChangesetStepSupport {
+    readonly seeds: readonly ScratchSeed[];
+    readonly describe: (input: never) => {
+        entity: string;
+        key: string;
+    };
+    /**
+     * Read-only snapshot of the touched entity (`undefined` = absent). For steps
+     * that create records with generated ids, the post-step snapshot receives the
+     * step result.
+     */
+    readonly snapshot: (adapter: PersistenceAdapter, input: never, result?: unknown) => Promise<unknown>;
+    /** Inverse invocations that undo the step, given the pre-step snapshot + result. */
+    readonly invert: (input: never, before: never, result: unknown) => readonly ChangesetInvocation[];
+}
+/** Whether an operation can be carried by a changeset (previewable + invertible). */
+export declare function isChangesetCapable(operation: string): boolean;
+/** Dotted names of every changeset-capable operation (sorted, deterministic). */
+export declare function changesetCapableOperations(): readonly string[];
+export interface CreateChangesetsOptions {
+    /** The only mutation path — the same adapter the operations client uses. */
+    adapter: PersistenceAdapter;
+    /** Share the operations client's bus so changeset + per-operation events interleave. */
+    events?: OperationEventBus;
+    /** Permission chokepoint for applied steps (pass-through by default, EC-150). */
+    authorize?: AuthorizationHook;
+    actor?: Principal;
+    /** Operation registry; defaults to every built-in definition. */
+    definitions?: ReadonlyMap<string, AnyOperationDefinition>;
+}
+export interface ChangesetOperations {
+    readonly events: OperationEventBus;
+    /** Build a draft changeset from ordered operation invocations. */
+    create(input: ChangesetInput): Changeset;
+    /** Dry-run: compute diff + issues against current state. Never mutates. */
+    preview(changeset: Changeset): Promise<OperationResult<Changeset>>;
+    /**
+     * Apply all steps atomically. Re-validates against current state first and is
+     * rejected while error-severity issues exist; a mid-apply failure rolls every
+     * applied step back.
+     */
+    apply(changeset: Changeset): Promise<OperationResult<Changeset>>;
+    /** Execute the inverse operations recorded at apply time, restoring prior state. */
+    revert(changeset: Changeset): Promise<OperationResult<Changeset>>;
+}
+export declare function createChangesets(options: CreateChangesetsOptions): ChangesetOperations;
+export {};