@pegma/authorization-admin 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RetireGolden, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @pegma/authorization-admin
+
+HTTP-neutral audited role administration for Authorization Core hosts.
+
+```sh
+npm install @pegma/authorization-admin @pegma/authorization-storage @pegma/storage-core
+```
+
+The package owns the role-management logic both reference hosts duplicated:
+a grants view with an explicit management policy, audited assign, audited
+revoke with the last-administrator guard (serialize, pre-check, re-verify,
+compensate), per-principal lifecycle history, and the one-time seed helper.
+The host owns the HTTP envelope, UI, principal lookup, rate limiting, and
+the authorization of the service's own callers — one admin tool per site,
+separate instances, nothing crossing hosts.
+
+See the [administration guide](https://github.com/pegma-dev/authorization-core/blob/main/docs/ADMINISTRATION.md).

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+/**
+ * HTTP-neutral audited role administration for Authorization Core hosts.
+ *
+ * Extracted from the two reference hosts per `docs/ADMINISTRATION.md`. The
+ * service owns grants rendering with an explicit management policy, audited
+ * assign, audited revoke with the last-administrator guard, per-principal
+ * lifecycle history, and the one-time seed helper. The HOST owns the HTTP
+ * envelope, UI, principal lookup, rate limiting, and the authorization of
+ * the service's own callers — nothing here re-checks permissions.
+ */
+import type { ActiveRoleAssignment, PrincipalId, RoleAssignmentActor, RoleAssignmentScope, RoleName } from "@pegma/authorization-contracts";
+import type { AuditedRoleAssignmentMutationStore, RoleAssignmentReader, VersionedRoleAssignment } from "@pegma/authorization-storage";
+/** The store surface the service needs: reads plus audited mutations. */
+export interface RoleAdministrationStore extends RoleAssignmentReader, AuditedRoleAssignmentMutationStore {
+}
+/** One superset row in the host's by-role holder index. */
+export interface RoleHolderIndexRow {
+    readonly principalId: PrincipalId;
+    readonly assignmentId: string;
+    readonly role: RoleName;
+}
+/**
+ * The host-provided by-role index (`docs/STORAGE.md` recipe): rows are
+ * written BEFORE grants, never deleted, and verified against the
+ * authoritative store on every read. The index may over-report; it must
+ * never under-report a grant that exists.
+ */
+export interface RoleHolderIndex {
+    readonly record: (row: RoleHolderIndexRow) => Promise<void>;
+    readonly listByRole: (role: RoleName) => Promise<readonly RoleHolderIndexRow[]>;
+}
+/** System actor written by the guard's post-revoke compensation grant. */
+export declare const GUARD_COMPENSATION_SYSTEM_ID = "last-administrator-guard";
+/** Default system actor for `ensureSeededAssignment`. */
+export declare const SEED_SYSTEM_ID = "bootstrap";
+/**
+ * Explicit management policy. Assignments granted by system actors are
+ * locked (`managedBy: "system"`) unless the actor is declared ONE-TIME
+ * here: a one-time actor writes once and never touches the assignment
+ * again, so the record is human-managed like any operator grant. The seed
+ * and guard-compensation actors are one-time by definition and are always
+ * included.
+ */
+export interface RoleManagementPolicy {
+    /** The role the last-administrator guard protects. */
+    readonly administratorRole: RoleName;
+    /** Additional host-declared one-time system actor ids. */
+    readonly oneTimeSystemActors?: ReadonlySet<string>;
+}
+/** Who may edit an assignment through the administration surface. */
+export type ManagedBy = "system" | "human";
+/** One active assignment with its management label. */
+export interface AdministeredAssignment {
+    readonly assignment: ActiveRoleAssignment;
+    readonly managedBy: ManagedBy;
+}
+/** One rendered lifecycle event for the per-principal history view. */
+export interface RoleAdministrationEvent {
+    readonly assignmentId: string;
+    readonly role: RoleName;
+    readonly kind: "granted" | "revoked";
+    readonly actor: RoleAssignmentActor;
+    readonly atEpochMs: number;
+    readonly reason?: string;
+}
+/** Command for an audited operator grant. */
+export interface AssignRoleCommand {
+    readonly principalId: PrincipalId;
+    readonly role: RoleName;
+    readonly scope: RoleAssignmentScope;
+    readonly actor: RoleAssignmentActor;
+}
+/** Result of one audited operator grant. */
+export type AssignRoleResult = Readonly<{
+    readonly status: "assigned";
+    readonly record: VersionedRoleAssignment<ActiveRoleAssignment>;
+}> | Readonly<{
+    readonly status: "duplicate";
+}> | Readonly<{
+    readonly status: "conflict";
+}>;
+/** Command for an audited operator revocation. */
+export interface RevokeRoleCommand {
+    readonly assignmentId: string;
+    readonly actor: RoleAssignmentActor;
+    readonly reason?: string;
+}
+/**
+ * Result of one audited operator revocation.
+ *
+ * `compensated` reports that the post-revoke re-verification found no
+ * active administrator remaining (a concurrent revoke on another instance
+ * won its race) and the guard wrote a compensation grant restoring the
+ * revoked principal. See "What the guard does NOT promise" in
+ * `docs/ADMINISTRATION.md` for the honest limits of this treatment.
+ */
+export type RevokeRoleResult = Readonly<{
+    readonly status: "revoked";
+    readonly compensated: boolean;
+}> | Readonly<{
+    readonly status: "not_found";
+}> | Readonly<{
+    readonly status: "already_revoked";
+}> | Readonly<{
+    readonly status: "system_managed";
+}> | Readonly<{
+    readonly status: "last_administrator";
+}> | Readonly<{
+    readonly status: "conflict";
+}>;
+/** Constructor options for {@link createRoleAdministration}. */
+export interface RoleAdministrationOptions {
+    readonly store: RoleAdministrationStore;
+    readonly holderIndex: RoleHolderIndex;
+    readonly policy: RoleManagementPolicy;
+    /** Epoch-milliseconds clock; injectable for deterministic tests. */
+    readonly now?: () => number;
+    /** Fresh opaque id source for grants and audit events. */
+    readonly generateId?: () => string;
+}
+/** The administration service. One instance per application; host-gated. */
+export interface RoleAdministration {
+    readonly viewGrants: (principalId: PrincipalId, scope: RoleAssignmentScope) => Promise<readonly AdministeredAssignment[]>;
+    readonly listHistory: (principalId: PrincipalId, scope: RoleAssignmentScope) => Promise<readonly RoleAdministrationEvent[]>;
+    readonly assignRole: (command: AssignRoleCommand) => Promise<AssignRoleResult>;
+    readonly revokeRole: (command: RevokeRoleCommand) => Promise<RevokeRoleResult>;
+    readonly anotherActiveHolderExists: (role: RoleName, scope: RoleAssignmentScope, excludingPrincipalId: PrincipalId | "") => Promise<boolean>;
+}
+/**
+ * Management label for one assignment under one policy. Grants by humans
+ * are human-managed; grants by system actors are locked unless the actor
+ * is one-time (the seed and guard-compensation actors always are).
+ */
+export declare function assignmentManagedBy(assignment: Pick<ActiveRoleAssignment, "grantedBy">, policy: RoleManagementPolicy): ManagedBy;
+/** Options for {@link ensureSeededAssignment}. */
+export interface EnsureSeededAssignmentOptions {
+    readonly store: RoleAdministrationStore;
+    /** When provided, the superset row is recorded before the grant. */
+    readonly holderIndex?: RoleHolderIndex;
+    readonly principalId: PrincipalId;
+    readonly role: RoleName;
+    readonly scope: RoleAssignmentScope;
+    /**
+     * Fresh opaque assignment id from the host's ceremony manifest, retained
+     * there for retries. NOT derived from the principal or role
+     * (`docs/ROLE_ASSIGNMENTS.md`); an exact replay is the store's ordinary
+     * `unchanged`, and the history check below converges even a lost
+     * manifest.
+     */
+    readonly assignmentId: string;
+    /** Audit event id, equally fresh and manifest-retained. */
+    readonly auditEventId: string;
+    readonly systemId?: string;
+    readonly now?: () => number;
+}
+/**
+ * Seed one role for one principal, once per principal AND ROLE, ever: any
+ * existing assignment record for that role — active or revoked, whatever
+ * its provenance — is durable already-seeded evidence, so a deliberate
+ * revocation is never resurrected by a lingering seed input. The ceremony
+ * in `docs/ADMINISTRATOR_BOOTSTRAP.md` decides whether and for whom to
+ * call this; the helper is a pure function over the ports.
+ *
+ * `conflict` means the manifest is CONTRADICTORY — its assignment id is
+ * already claimed by a different lifecycle — and the principal may still
+ * hold nothing: the ceremony must fail closed, not report convergence.
+ * (A concurrent duplicate run converges through the store's `unchanged`
+ * replay, never through a conflict.)
+ */
+export declare function ensureSeededAssignment(options: EnsureSeededAssignmentOptions): Promise<"granted" | "already" | "conflict">;
+/** Creates the administration service over host-owned ports. */
+export declare function createRoleAdministration(options: RoleAdministrationOptions): RoleAdministration;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,271 @@
+/** System actor written by the guard's post-revoke compensation grant. */
+export const GUARD_COMPENSATION_SYSTEM_ID = "last-administrator-guard";
+/** Default system actor for `ensureSeededAssignment`. */
+export const SEED_SYSTEM_ID = "bootstrap";
+const alwaysOneTime = new Set([GUARD_COMPENSATION_SYSTEM_ID, SEED_SYSTEM_ID]);
+/**
+ * Management label for one assignment under one policy. Grants by humans
+ * are human-managed; grants by system actors are locked unless the actor
+ * is one-time (the seed and guard-compensation actors always are).
+ */
+export function assignmentManagedBy(assignment, policy) {
+    const grantedBy = assignment.grantedBy;
+    if (grantedBy.kind !== "system") {
+        return "human";
+    }
+    return alwaysOneTime.has(grantedBy.systemId) ||
+        (policy.oneTimeSystemActors?.has(grantedBy.systemId) ?? false)
+        ? "human"
+        : "system";
+}
+/**
+ * Seed one role for one principal, once per principal AND ROLE, ever: any
+ * existing assignment record for that role — active or revoked, whatever
+ * its provenance — is durable already-seeded evidence, so a deliberate
+ * revocation is never resurrected by a lingering seed input. The ceremony
+ * in `docs/ADMINISTRATOR_BOOTSTRAP.md` decides whether and for whom to
+ * call this; the helper is a pure function over the ports.
+ *
+ * `conflict` means the manifest is CONTRADICTORY — its assignment id is
+ * already claimed by a different lifecycle — and the principal may still
+ * hold nothing: the ceremony must fail closed, not report convergence.
+ * (A concurrent duplicate run converges through the store's `unchanged`
+ * replay, never through a conflict.)
+ */
+export async function ensureSeededAssignment(options) {
+    const { store, holderIndex, principalId, role, scope } = options;
+    const history = await store.listRoleAssignments(principalId, scope);
+    if (history.some((assignment) => assignment.role === role)) {
+        return "already";
+    }
+    if (holderIndex !== undefined) {
+        await holderIndex.record({
+            principalId,
+            assignmentId: options.assignmentId,
+            role,
+        });
+    }
+    const result = await store.grantRoleAssignmentWithAudit({
+        assignment: {
+            id: options.assignmentId,
+            principalId,
+            role,
+            scope,
+            grantedBy: {
+                kind: "system",
+                systemId: options.systemId ?? SEED_SYSTEM_ID,
+            },
+            grantedAtEpochMs: (options.now ?? Date.now)(),
+            status: "active",
+        },
+        auditEventId: options.auditEventId,
+    });
+    if (result.status === "granted") {
+        return "granted";
+    }
+    return result.status === "unchanged" ? "already" : "conflict";
+}
+/** Exact-scope equality: the guard never counts holders across scopes. */
+function sameScope(left, right) {
+    if (left.kind === "application") {
+        return right.kind === "application";
+    }
+    return (right.kind === "organization" &&
+        right.organizationId === left.organizationId);
+}
+/** Creates the administration service over host-owned ports. */
+export function createRoleAdministration(options) {
+    const { store, holderIndex, policy } = options;
+    const now = options.now ?? (() => Date.now());
+    const generateId = options.generateId ?? (() => crypto.randomUUID());
+    const anotherActiveHolderExists = async (role, scope, excludingPrincipalId) => {
+        const candidates = await holderIndex.listByRole(role);
+        for (const candidate of candidates) {
+            if (candidate.principalId === excludingPrincipalId) {
+                continue;
+            }
+            // Rows are candidates only; the authoritative store decides — and
+            // only an EXACT-scope holder counts: an organization-scoped
+            // administrator is no answer to losing the last application-scoped
+            // one.
+            const current = await store.getRoleAssignment(candidate.assignmentId);
+            if (current !== null &&
+                current.assignment.status === "active" &&
+                current.assignment.role === role &&
+                current.assignment.principalId === candidate.principalId &&
+                sameScope(current.assignment.scope, scope)) {
+                return true;
+            }
+        }
+        return false;
+    };
+    // Revocations are serialized in-process so two concurrent revokes of the
+    // two last administrators cannot interleave past the guard. The chain
+    // never rejects: each task's failure belongs to its own caller.
+    let revokeChain = Promise.resolve();
+    const serialized = (task) => {
+        const next = revokeChain.then(task, task);
+        revokeChain = next.catch(() => undefined);
+        return next;
+    };
+    const revokeRole = (command) => serialized(async () => {
+        const current = await store.getRoleAssignment(command.assignmentId);
+        if (current === null) {
+            return { status: "not_found" };
+        }
+        if (current.assignment.status === "revoked") {
+            return { status: "already_revoked" };
+        }
+        const assignment = current.assignment;
+        if (assignmentManagedBy(assignment, policy) === "system") {
+            return { status: "system_managed" };
+        }
+        const guarded = assignment.role === policy.administratorRole;
+        if (guarded &&
+            !(await anotherActiveHolderExists(assignment.role, assignment.scope, assignment.principalId))) {
+            return { status: "last_administrator" };
+        }
+        const revoked = await store.revokeRoleAssignmentWithAudit({
+            assignmentId: assignment.id,
+            expectedConcurrencyToken: current.concurrencyToken,
+            revokedBy: command.actor,
+            revokedAtEpochMs: now(),
+            ...(command.reason === undefined ? {} : { reason: command.reason }),
+            auditEventId: generateId(),
+        });
+        if (revoked.status === "not_found") {
+            return { status: "not_found" };
+        }
+        if (revoked.status === "conflict") {
+            return { status: "conflict" };
+        }
+        if (!guarded) {
+            return { status: "revoked", compensated: false };
+        }
+        // Re-verify after the commit: a concurrent revoke on ANOTHER instance
+        // may have removed the holder the pre-check relied on. If no active
+        // administrator remains, restore the principal just revoked with a
+        // one-time system actor (human-managed, revocable). The residual
+        // crash window and its documented recovery live in
+        // docs/ADMINISTRATION.md.
+        if (await anotherActiveHolderExists(assignment.role, assignment.scope, "")) {
+            return { status: "revoked", compensated: false };
+        }
+        const compensationId = generateId();
+        await holderIndex.record({
+            principalId: assignment.principalId,
+            assignmentId: compensationId,
+            role: assignment.role,
+        });
+        const compensation = await store.grantRoleAssignmentWithAudit({
+            assignment: {
+                id: compensationId,
+                principalId: assignment.principalId,
+                role: assignment.role,
+                scope: assignment.scope,
+                grantedBy: {
+                    kind: "system",
+                    systemId: GUARD_COMPENSATION_SYSTEM_ID,
+                },
+                grantedAtEpochMs: now(),
+                status: "active",
+            },
+            auditEventId: generateId(),
+        });
+        if (compensation.status === "conflict") {
+            // `active_tuple` means another writer restored this principal in
+            // the meantime — verify that an administrator genuinely exists
+            // before declining to compensate. Anything else unverified is the
+            // documented crash-window failure: surface it, never report a
+            // guarantee that does not hold.
+            if (await anotherActiveHolderExists(assignment.role, assignment.scope, "")) {
+                return { status: "revoked", compensated: false };
+            }
+            throw new Error("administrator compensation failed; recover via the bootstrap ceremony (docs/ADMINISTRATION.md)");
+        }
+        return { status: "revoked", compensated: true };
+    });
+    const service = {
+        async viewGrants(principalId, scope) {
+            const active = await store.listActiveRoleAssignments(principalId, scope);
+            // Self-heal the superset: an assignment the store reports but the
+            // index misses (a grant that predates the index) is re-recorded so
+            // the guard's by-role candidate set converges. Idempotent puts.
+            for (const assignment of active) {
+                await holderIndex.record({
+                    principalId,
+                    assignmentId: assignment.id,
+                    role: assignment.role,
+                });
+            }
+            return active.map((assignment) => ({
+                assignment,
+                managedBy: assignmentManagedBy(assignment, policy),
+            }));
+        },
+        async listHistory(principalId, scope) {
+            const held = await store.listRoleAssignments(principalId, scope);
+            const events = [];
+            for (const assignment of held) {
+                events.push({
+                    assignmentId: assignment.id,
+                    role: assignment.role,
+                    kind: "granted",
+                    actor: assignment.grantedBy,
+                    atEpochMs: assignment.grantedAtEpochMs,
+                });
+                if (assignment.status === "revoked") {
+                    events.push({
+                        assignmentId: assignment.id,
+                        role: assignment.role,
+                        kind: "revoked",
+                        actor: assignment.revokedBy,
+                        atEpochMs: assignment.revokedAtEpochMs,
+                        ...(assignment.reason === undefined
+                            ? {}
+                            : { reason: assignment.reason }),
+                    });
+                }
+            }
+            events.sort((left, right) => left.atEpochMs - right.atEpochMs);
+            return events;
+        },
+        async assignRole(command) {
+            const active = await store.listActiveRoleAssignments(command.principalId, command.scope);
+            // Pre-check so a routine duplicate never writes an index row; the
+            // store's active-tuple guarantee still decides races past this.
+            if (active.some((assignment) => assignment.role === command.role)) {
+                return { status: "duplicate" };
+            }
+            const assignmentId = generateId();
+            await holderIndex.record({
+                principalId: command.principalId,
+                assignmentId,
+                role: command.role,
+            });
+            const result = await store.grantRoleAssignmentWithAudit({
+                assignment: {
+                    id: assignmentId,
+                    principalId: command.principalId,
+                    role: command.role,
+                    scope: command.scope,
+                    grantedBy: command.actor,
+                    grantedAtEpochMs: now(),
+                    status: "active",
+                },
+                auditEventId: generateId(),
+            });
+            if (result.status === "granted") {
+                return { status: "assigned", record: result.record };
+            }
+            if (result.status === "conflict" && result.reason === "active_tuple") {
+                return { status: "duplicate" };
+            }
+            return { status: "conflict" };
+        },
+        revokeRole,
+        anotherActiveHolderExists,
+    };
+    return Object.freeze(service);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTTP-neutral audited role administration for Authorization Core hosts.\n *\n * Extracted from the two reference hosts per `docs/ADMINISTRATION.md`. The\n * service owns grants rendering with an explicit management policy, audited\n * assign, audited revoke with the last-administrator guard, per-principal\n * lifecycle history, and the one-time seed helper. The HOST owns the HTTP\n * envelope, UI, principal lookup, rate limiting, and the authorization of\n * the service's own callers — nothing here re-checks permissions.\n */\nimport type {\n  ActiveRoleAssignment,\n  PrincipalId,\n  RoleAssignmentActor,\n  RoleAssignmentScope,\n  RoleName,\n} from \"@pegma/authorization-contracts\";\nimport type {\n  AuditedRoleAssignmentMutationStore,\n  RoleAssignmentReader,\n  VersionedRoleAssignment,\n} from \"@pegma/authorization-storage\";\n\n/** The store surface the service needs: reads plus audited mutations. */\nexport interface RoleAdministrationStore\n  extends RoleAssignmentReader, AuditedRoleAssignmentMutationStore {}\n\n/** One superset row in the host's by-role holder index. */\nexport interface RoleHolderIndexRow {\n  readonly principalId: PrincipalId;\n  readonly assignmentId: string;\n  readonly role: RoleName;\n}\n\n/**\n * The host-provided by-role index (`docs/STORAGE.md` recipe): rows are\n * written BEFORE grants, never deleted, and verified against the\n * authoritative store on every read. The index may over-report; it must\n * never under-report a grant that exists.\n */\nexport interface RoleHolderIndex {\n  readonly record: (row: RoleHolderIndexRow) => Promise<void>;\n  readonly listByRole: (\n    role: RoleName,\n  ) => Promise<readonly RoleHolderIndexRow[]>;\n}\n\n/** System actor written by the guard's post-revoke compensation grant. */\nexport const GUARD_COMPENSATION_SYSTEM_ID = \"last-administrator-guard\";\n\n/** Default system actor for `ensureSeededAssignment`. */\nexport const SEED_SYSTEM_ID = \"bootstrap\";\n\n/**\n * Explicit management policy. Assignments granted by system actors are\n * locked (`managedBy: \"system\"`) unless the actor is declared ONE-TIME\n * here: a one-time actor writes once and never touches the assignment\n * again, so the record is human-managed like any operator grant. The seed\n * and guard-compensation actors are one-time by definition and are always\n * included.\n */\nexport interface RoleManagementPolicy {\n  /** The role the last-administrator guard protects. */\n  readonly administratorRole: RoleName;\n  /** Additional host-declared one-time system actor ids. */\n  readonly oneTimeSystemActors?: ReadonlySet<string>;\n}\n\n/** Who may edit an assignment through the administration surface. */\nexport type ManagedBy = \"system\" | \"human\";\n\n/** One active assignment with its management label. */\nexport interface AdministeredAssignment {\n  readonly assignment: ActiveRoleAssignment;\n  readonly managedBy: ManagedBy;\n}\n\n/** One rendered lifecycle event for the per-principal history view. */\nexport interface RoleAdministrationEvent {\n  readonly assignmentId: string;\n  readonly role: RoleName;\n  readonly kind: \"granted\" | \"revoked\";\n  readonly actor: RoleAssignmentActor;\n  readonly atEpochMs: number;\n  readonly reason?: string;\n}\n\n/** Command for an audited operator grant. */\nexport interface AssignRoleCommand {\n  readonly principalId: PrincipalId;\n  readonly role: RoleName;\n  readonly scope: RoleAssignmentScope;\n  readonly actor: RoleAssignmentActor;\n}\n\n/** Result of one audited operator grant. */\nexport type AssignRoleResult =\n  | Readonly<{\n      readonly status: \"assigned\";\n      readonly record: VersionedRoleAssignment<ActiveRoleAssignment>;\n    }>\n  | Readonly<{ readonly status: \"duplicate\" }>\n  | Readonly<{ readonly status: \"conflict\" }>;\n\n/** Command for an audited operator revocation. */\nexport interface RevokeRoleCommand {\n  readonly assignmentId: string;\n  readonly actor: RoleAssignmentActor;\n  readonly reason?: string;\n}\n\n/**\n * Result of one audited operator revocation.\n *\n * `compensated` reports that the post-revoke re-verification found no\n * active administrator remaining (a concurrent revoke on another instance\n * won its race) and the guard wrote a compensation grant restoring the\n * revoked principal. See \"What the guard does NOT promise\" in\n * `docs/ADMINISTRATION.md` for the honest limits of this treatment.\n */\nexport type RevokeRoleResult =\n  | Readonly<{\n      readonly status: \"revoked\";\n      readonly compensated: boolean;\n    }>\n  | Readonly<{ readonly status: \"not_found\" }>\n  | Readonly<{ readonly status: \"already_revoked\" }>\n  | Readonly<{ readonly status: \"system_managed\" }>\n  | Readonly<{ readonly status: \"last_administrator\" }>\n  | Readonly<{ readonly status: \"conflict\" }>;\n\n/** Constructor options for {@link createRoleAdministration}. */\nexport interface RoleAdministrationOptions {\n  readonly store: RoleAdministrationStore;\n  readonly holderIndex: RoleHolderIndex;\n  readonly policy: RoleManagementPolicy;\n  /** Epoch-milliseconds clock; injectable for deterministic tests. */\n  readonly now?: () => number;\n  /** Fresh opaque id source for grants and audit events. */\n  readonly generateId?: () => string;\n}\n\n/** The administration service. One instance per application; host-gated. */\nexport interface RoleAdministration {\n  readonly viewGrants: (\n    principalId: PrincipalId,\n    scope: RoleAssignmentScope,\n  ) => Promise<readonly AdministeredAssignment[]>;\n  readonly listHistory: (\n    principalId: PrincipalId,\n    scope: RoleAssignmentScope,\n  ) => Promise<readonly RoleAdministrationEvent[]>;\n  readonly assignRole: (\n    command: AssignRoleCommand,\n  ) => Promise<AssignRoleResult>;\n  readonly revokeRole: (\n    command: RevokeRoleCommand,\n  ) => Promise<RevokeRoleResult>;\n  readonly anotherActiveHolderExists: (\n    role: RoleName,\n    scope: RoleAssignmentScope,\n    excludingPrincipalId: PrincipalId | \"\",\n  ) => Promise<boolean>;\n}\n\nconst alwaysOneTime = new Set([GUARD_COMPENSATION_SYSTEM_ID, SEED_SYSTEM_ID]);\n\n/**\n * Management label for one assignment under one policy. Grants by humans\n * are human-managed; grants by system actors are locked unless the actor\n * is one-time (the seed and guard-compensation actors always are).\n */\nexport function assignmentManagedBy(\n  assignment: Pick<ActiveRoleAssignment, \"grantedBy\">,\n  policy: RoleManagementPolicy,\n): ManagedBy {\n  const grantedBy = assignment.grantedBy;\n  if (grantedBy.kind !== \"system\") {\n    return \"human\";\n  }\n  return alwaysOneTime.has(grantedBy.systemId) ||\n    (policy.oneTimeSystemActors?.has(grantedBy.systemId) ?? false)\n    ? \"human\"\n    : \"system\";\n}\n\n/** Options for {@link ensureSeededAssignment}. */\nexport interface EnsureSeededAssignmentOptions {\n  readonly store: RoleAdministrationStore;\n  /** When provided, the superset row is recorded before the grant. */\n  readonly holderIndex?: RoleHolderIndex;\n  readonly principalId: PrincipalId;\n  readonly role: RoleName;\n  readonly scope: RoleAssignmentScope;\n  /**\n   * Fresh opaque assignment id from the host's ceremony manifest, retained\n   * there for retries. NOT derived from the principal or role\n   * (`docs/ROLE_ASSIGNMENTS.md`); an exact replay is the store's ordinary\n   * `unchanged`, and the history check below converges even a lost\n   * manifest.\n   */\n  readonly assignmentId: string;\n  /** Audit event id, equally fresh and manifest-retained. */\n  readonly auditEventId: string;\n  readonly systemId?: string;\n  readonly now?: () => number;\n}\n\n/**\n * Seed one role for one principal, once per principal AND ROLE, ever: any\n * existing assignment record for that role — active or revoked, whatever\n * its provenance — is durable already-seeded evidence, so a deliberate\n * revocation is never resurrected by a lingering seed input. The ceremony\n * in `docs/ADMINISTRATOR_BOOTSTRAP.md` decides whether and for whom to\n * call this; the helper is a pure function over the ports.\n *\n * `conflict` means the manifest is CONTRADICTORY — its assignment id is\n * already claimed by a different lifecycle — and the principal may still\n * hold nothing: the ceremony must fail closed, not report convergence.\n * (A concurrent duplicate run converges through the store's `unchanged`\n * replay, never through a conflict.)\n */\nexport async function ensureSeededAssignment(\n  options: EnsureSeededAssignmentOptions,\n): Promise<\"granted\" | \"already\" | \"conflict\"> {\n  const { store, holderIndex, principalId, role, scope } = options;\n  const history = await store.listRoleAssignments(principalId, scope);\n  if (history.some((assignment) => assignment.role === role)) {\n    return \"already\";\n  }\n  if (holderIndex !== undefined) {\n    await holderIndex.record({\n      principalId,\n      assignmentId: options.assignmentId,\n      role,\n    });\n  }\n  const result = await store.grantRoleAssignmentWithAudit({\n    assignment: {\n      id: options.assignmentId,\n      principalId,\n      role,\n      scope,\n      grantedBy: {\n        kind: \"system\",\n        systemId: options.systemId ?? SEED_SYSTEM_ID,\n      },\n      grantedAtEpochMs: (options.now ?? Date.now)(),\n      status: \"active\",\n    },\n    auditEventId: options.auditEventId,\n  });\n  if (result.status === \"granted\") {\n    return \"granted\";\n  }\n  return result.status === \"unchanged\" ? \"already\" : \"conflict\";\n}\n\n/** Exact-scope equality: the guard never counts holders across scopes. */\nfunction sameScope(\n  left: RoleAssignmentScope,\n  right: RoleAssignmentScope,\n): boolean {\n  if (left.kind === \"application\") {\n    return right.kind === \"application\";\n  }\n  return (\n    right.kind === \"organization\" &&\n    right.organizationId === left.organizationId\n  );\n}\n\n/** Creates the administration service over host-owned ports. */\nexport function createRoleAdministration(\n  options: RoleAdministrationOptions,\n): RoleAdministration {\n  const { store, holderIndex, policy } = options;\n  const now = options.now ?? (() => Date.now());\n  const generateId = options.generateId ?? (() => crypto.randomUUID());\n\n  const anotherActiveHolderExists = async (\n    role: RoleName,\n    scope: RoleAssignmentScope,\n    excludingPrincipalId: PrincipalId | \"\",\n  ): Promise<boolean> => {\n    const candidates = await holderIndex.listByRole(role);\n    for (const candidate of candidates) {\n      if (candidate.principalId === excludingPrincipalId) {\n        continue;\n      }\n      // Rows are candidates only; the authoritative store decides — and\n      // only an EXACT-scope holder counts: an organization-scoped\n      // administrator is no answer to losing the last application-scoped\n      // one.\n      const current = await store.getRoleAssignment(candidate.assignmentId);\n      if (\n        current !== null &&\n        current.assignment.status === \"active\" &&\n        current.assignment.role === role &&\n        current.assignment.principalId === candidate.principalId &&\n        sameScope(current.assignment.scope, scope)\n      ) {\n        return true;\n      }\n    }\n    return false;\n  };\n\n  // Revocations are serialized in-process so two concurrent revokes of the\n  // two last administrators cannot interleave past the guard. The chain\n  // never rejects: each task's failure belongs to its own caller.\n  let revokeChain: Promise<unknown> = Promise.resolve();\n  const serialized = <T>(task: () => Promise<T>): Promise<T> => {\n    const next = revokeChain.then(task, task);\n    revokeChain = next.catch(() => undefined);\n    return next;\n  };\n\n  const revokeRole = (command: RevokeRoleCommand): Promise<RevokeRoleResult> =>\n    serialized(async () => {\n      const current = await store.getRoleAssignment(command.assignmentId);\n      if (current === null) {\n        return { status: \"not_found\" };\n      }\n      if (current.assignment.status === \"revoked\") {\n        return { status: \"already_revoked\" };\n      }\n      const assignment = current.assignment;\n      if (assignmentManagedBy(assignment, policy) === \"system\") {\n        return { status: \"system_managed\" };\n      }\n      const guarded = assignment.role === policy.administratorRole;\n      if (\n        guarded &&\n        !(await anotherActiveHolderExists(\n          assignment.role,\n          assignment.scope,\n          assignment.principalId,\n        ))\n      ) {\n        return { status: \"last_administrator\" };\n      }\n      const revoked = await store.revokeRoleAssignmentWithAudit({\n        assignmentId: assignment.id,\n        expectedConcurrencyToken: current.concurrencyToken,\n        revokedBy: command.actor,\n        revokedAtEpochMs: now(),\n        ...(command.reason === undefined ? {} : { reason: command.reason }),\n        auditEventId: generateId(),\n      });\n      if (revoked.status === \"not_found\") {\n        return { status: \"not_found\" };\n      }\n      if (revoked.status === \"conflict\") {\n        return { status: \"conflict\" };\n      }\n      if (!guarded) {\n        return { status: \"revoked\", compensated: false };\n      }\n      // Re-verify after the commit: a concurrent revoke on ANOTHER instance\n      // may have removed the holder the pre-check relied on. If no active\n      // administrator remains, restore the principal just revoked with a\n      // one-time system actor (human-managed, revocable). The residual\n      // crash window and its documented recovery live in\n      // docs/ADMINISTRATION.md.\n      if (\n        await anotherActiveHolderExists(assignment.role, assignment.scope, \"\")\n      ) {\n        return { status: \"revoked\", compensated: false };\n      }\n      const compensationId = generateId();\n      await holderIndex.record({\n        principalId: assignment.principalId,\n        assignmentId: compensationId,\n        role: assignment.role,\n      });\n      const compensation = await store.grantRoleAssignmentWithAudit({\n        assignment: {\n          id: compensationId,\n          principalId: assignment.principalId,\n          role: assignment.role,\n          scope: assignment.scope,\n          grantedBy: {\n            kind: \"system\",\n            systemId: GUARD_COMPENSATION_SYSTEM_ID,\n          },\n          grantedAtEpochMs: now(),\n          status: \"active\",\n        },\n        auditEventId: generateId(),\n      });\n      if (compensation.status === \"conflict\") {\n        // `active_tuple` means another writer restored this principal in\n        // the meantime — verify that an administrator genuinely exists\n        // before declining to compensate. Anything else unverified is the\n        // documented crash-window failure: surface it, never report a\n        // guarantee that does not hold.\n        if (\n          await anotherActiveHolderExists(assignment.role, assignment.scope, \"\")\n        ) {\n          return { status: \"revoked\", compensated: false };\n        }\n        throw new Error(\n          \"administrator compensation failed; recover via the bootstrap ceremony (docs/ADMINISTRATION.md)\",\n        );\n      }\n      return { status: \"revoked\", compensated: true };\n    });\n\n  const service: RoleAdministration = {\n    async viewGrants(principalId, scope) {\n      const active = await store.listActiveRoleAssignments(principalId, scope);\n      // Self-heal the superset: an assignment the store reports but the\n      // index misses (a grant that predates the index) is re-recorded so\n      // the guard's by-role candidate set converges. Idempotent puts.\n      for (const assignment of active) {\n        await holderIndex.record({\n          principalId,\n          assignmentId: assignment.id,\n          role: assignment.role,\n        });\n      }\n      return active.map((assignment) => ({\n        assignment,\n        managedBy: assignmentManagedBy(assignment, policy),\n      }));\n    },\n\n    async listHistory(principalId, scope) {\n      const held = await store.listRoleAssignments(principalId, scope);\n      const events: RoleAdministrationEvent[] = [];\n      for (const assignment of held) {\n        events.push({\n          assignmentId: assignment.id,\n          role: assignment.role,\n          kind: \"granted\",\n          actor: assignment.grantedBy,\n          atEpochMs: assignment.grantedAtEpochMs,\n        });\n        if (assignment.status === \"revoked\") {\n          events.push({\n            assignmentId: assignment.id,\n            role: assignment.role,\n            kind: \"revoked\",\n            actor: assignment.revokedBy,\n            atEpochMs: assignment.revokedAtEpochMs,\n            ...(assignment.reason === undefined\n              ? {}\n              : { reason: assignment.reason }),\n          });\n        }\n      }\n      events.sort((left, right) => left.atEpochMs - right.atEpochMs);\n      return events;\n    },\n\n    async assignRole(command) {\n      const active = await store.listActiveRoleAssignments(\n        command.principalId,\n        command.scope,\n      );\n      // Pre-check so a routine duplicate never writes an index row; the\n      // store's active-tuple guarantee still decides races past this.\n      if (active.some((assignment) => assignment.role === command.role)) {\n        return { status: \"duplicate\" };\n      }\n      const assignmentId = generateId();\n      await holderIndex.record({\n        principalId: command.principalId,\n        assignmentId,\n        role: command.role,\n      });\n      const result = await store.grantRoleAssignmentWithAudit({\n        assignment: {\n          id: assignmentId,\n          principalId: command.principalId,\n          role: command.role,\n          scope: command.scope,\n          grantedBy: command.actor,\n          grantedAtEpochMs: now(),\n          status: \"active\",\n        },\n        auditEventId: generateId(),\n      });\n      if (result.status === \"granted\") {\n        return { status: \"assigned\", record: result.record };\n      }\n      if (result.status === \"conflict\" && result.reason === \"active_tuple\") {\n        return { status: \"duplicate\" };\n      }\n      return { status: \"conflict\" };\n    },\n\n    revokeRole,\n    anotherActiveHolderExists,\n  };\n  return Object.freeze(service);\n}\n"]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@pegma/authorization-admin",
+  "version": "0.0.0",
+  "description": "HTTP-neutral audited role-administration service for Authorization Core hosts.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/*.js",
+    "dist/**/*.js.map"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pegma-dev/authorization-core.git",
+    "directory": "packages/admin"
+  },
+  "dependencies": {
+    "@pegma/authorization-contracts": "0.3.0",
+    "@pegma/authorization-storage": "0.3.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}