@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/platform/security/policy.ts

@@ -0,0 +1,286 @@
+import { assertActiveContext } from "../../core/context.js";
+import type { ExecutionContext } from "../../core/types.js";
+import { Item } from "../../items/item.js";
+import type {
+    HarnessStorage,
+    CatalogEntry,
+    ItemTypeDefinition,
+    StorageValue,
+    StoredItem,
+} from "../../storage/types.js";
+import type { Classifications } from "../classifications.js";
+import { ApplicationError, PlatformError } from "../errors.js";
+import { recordKey } from "../references/catalog.js";
+import type { PlatformTrace } from "../trace.js";
+import { IdentityGrants } from "./grants.js";
+import { Identities } from "./identities.js";
+import { MethodExecutionScopes } from "./method-execution.js";
+import { AccessRight, ItemPermissions } from "./permissions.js";
+import { SourceAccess } from "./source-access.js";
+import { SourceInheritance } from "./source-inheritance.js";
+import { AuthorizationMode } from "./types.js";
+import type { AuthorizationPolicy, AuthorizationRequest } from "./types.js";
+
+interface OwnedDeletion {
+    readonly recordKey: string;
+}
+
+export class NativeSecurity {
+    readonly methods = new MethodExecutionScopes();
+    readonly grants: IdentityGrants;
+    readonly permissions: ItemPermissions;
+    private readonly identities: Identities;
+    private readonly inheritance: SourceInheritance;
+    private readonly sources: SourceAccess;
+    private readonly ownedDeletes = new Map<string, OwnedDeletion>();
+
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly mode: AuthorizationPolicy | undefined,
+        userId: (() => string) | undefined,
+        private readonly now: () => Date,
+        trace: PlatformTrace,
+        classifications: Classifications,
+    ) {
+        this.identities = new Identities(storage, userId, now);
+        this.grants = new IdentityGrants(this.identities, trace);
+        this.permissions = new ItemPermissions(
+            storage,
+            this.identities,
+            this.grants,
+            now,
+            classifications,
+        );
+        this.sources = new SourceAccess(storage);
+        this.inheritance = new SourceInheritance(storage, this.sources, trace, this.permissions);
+    }
+
+    get enabled(): boolean {
+        return this.mode === AuthorizationMode.Native;
+    }
+
+    reset(): void {
+        this.ownedDeletes.clear();
+        this.methods.reset();
+    }
+
+    authorize(request: AuthorizationRequest, context: ExecutionContext): void {
+        assertActiveContext(context);
+        this.identities.user();
+
+        if (request.kind === "action") {
+            return;
+        }
+
+        let identity: StorageValue | undefined;
+
+        if (request.kind === "method") {
+            const method = this.storage
+                .listCatalogEntries("Method")
+                .find(
+                    (entry) =>
+                        String(entry.properties.name).toLowerCase() === request.name.toLowerCase(),
+                );
+            identity = method?.properties.execution_allowed_to;
+        } else {
+            identity = this.storage.getCatalogEntry("Life Cycle Transition", request.name)
+                ?.properties.role;
+        }
+
+        if (
+            identity !== undefined &&
+            identity !== null &&
+            identity !== "" &&
+            !this.grants
+                .current(context)
+                .some((id) => id.toLowerCase() === String(identity).toLowerCase())
+        ) {
+            throw new ApplicationError(
+                Item.error(`Identity does not permit '${request.name}'.`, "PermissionDenied"),
+            );
+        }
+    }
+
+    authorizeMethodSession(context: ExecutionContext): void {
+        assertActiveContext(context);
+        this.identities.user();
+    }
+
+    readable(
+        definition: ItemTypeDefinition,
+        records: readonly StoredItem[],
+        context: ExecutionContext,
+    ) {
+        if (records.length > 0 && records.every((record) => this.ownsDeletion(record, context))) {
+            return records;
+        }
+
+        return this.enabled ? this.permissions.readable(definition, records, context) : records;
+    }
+
+    assertMutation(
+        definition: ItemTypeDefinition,
+        record: StoredItem,
+        action: string,
+        context: ExecutionContext,
+    ): void {
+        // Unlock checks persisted lock ownership, including after an ACL or state change.
+        if (
+            !this.enabled ||
+            action === "unlock" ||
+            (action === "delete" && this.ownsDeletion(record, context))
+        ) {
+            return;
+        }
+
+        const right = action === "delete" ? AccessRight.Delete : AccessRight.Update;
+        this.permissions.assert(definition, record, right, context);
+    }
+
+    async deletingOwned(
+        record: StoredItem,
+        context: ExecutionContext,
+        apply: () => Promise<Item>,
+    ): Promise<Item> {
+        assertActiveContext(context);
+        const scope = { recordKey: recordKey(record) };
+        this.ownedDeletes.set(context.executionId, scope);
+
+        try {
+            return await apply();
+        } finally {
+            if (this.ownedDeletes.get(context.executionId) === scope) {
+                this.ownedDeletes.delete(context.executionId);
+            }
+        }
+    }
+
+    private ownsDeletion(record: StoredItem, context: ExecutionContext): boolean {
+        return (
+            this.ownedDeletes.get(context.parentExecutionId ?? "")?.recordKey === recordKey(record)
+        );
+    }
+
+    creation(
+        definition: ItemTypeDefinition,
+        values: Readonly<Record<string, StorageValue>>,
+        context: ExecutionContext,
+    ) {
+        return this.enabled ? this.permissions.creation(definition, values, context) : {};
+    }
+
+    assertCanReclassify(
+        definition: ItemTypeDefinition,
+        classification: string,
+        context: ExecutionContext,
+    ): void {
+        if (this.enabled) {
+            this.permissions.assertCanReclassify(definition, classification, context);
+        }
+    }
+
+    assertAccessChange(
+        definition: ItemTypeDefinition,
+        record: StoredItem,
+        changes: Readonly<Record<string, StorageValue>>,
+        context: ExecutionContext,
+        classificationChanged = false,
+    ): void {
+        if (
+            this.enabled &&
+            changes.source_id !== undefined &&
+            String(changes.source_id).toLowerCase() !==
+                String(record.properties.source_id).toLowerCase() &&
+            this.sources.inherited(definition)
+        ) {
+            throw new PlatformError(
+                "UnsupportedSourceAccessMove",
+                "Moving an inherited relationship to another source requires its own permission policy.",
+                definition.source ? { source: definition.source } : undefined,
+            );
+        }
+
+        if (
+            this.enabled &&
+            changes.permission_id !== undefined &&
+            String(changes.permission_id).toLowerCase() !==
+                String(record.properties.permission_id).toLowerCase()
+        ) {
+            if (!classificationChanged) {
+                this.assertPermissionChange(definition, record, context);
+            }
+
+            this.permissions.assertSelectedPermission(
+                definition,
+                String(changes.permission_id),
+                context,
+                record.properties.current_state,
+            );
+        }
+    }
+
+    assertPermissionChange(
+        definition: ItemTypeDefinition,
+        record: StoredItem,
+        context: ExecutionContext,
+    ): void {
+        if (this.enabled) {
+            this.permissions.assert(definition, record, AccessRight.ChangeAccess, context);
+        }
+    }
+
+    changed(before: StoredItem, after: StoredItem, context: ExecutionContext): void {
+        if (this.enabled) {
+            this.inheritance.changed(before, after, context);
+        }
+    }
+
+    copied(
+        definition: ItemTypeDefinition,
+        values: Readonly<Record<string, StorageValue>>,
+        context: ExecutionContext,
+    ): Readonly<Record<string, StorageValue>> {
+        if (!this.enabled || !this.sources.inherited(definition)) {
+            return {};
+        }
+
+        const source = this.sources.owner(definition, values, context);
+
+        return this.permissions.sourceProperties(source.definition, source.record, context);
+    }
+
+    transition(transition: CatalogEntry, record: StoredItem, context: ExecutionContext): void {
+        const role = transition.properties.role;
+
+        if (role !== undefined && role !== null && role !== "") {
+            this.permissions.assertIdentity(String(role), record, context);
+        }
+    }
+
+    auditedChanges(
+        record: StoredItem,
+        changes: Record<string, StorageValue>,
+    ): Record<string, StorageValue> {
+        if (!this.enabled) {
+            return changes;
+        }
+
+        for (const property of ["created_by_id", "created_on"]) {
+            if (
+                changes[property] !== undefined &&
+                changes[property] !== record.properties[property]
+            ) {
+                throw new PlatformError(
+                    "ManagedProperty",
+                    `Cannot change '${property}' on an existing Item.`,
+                );
+            }
+        }
+
+        return {
+            ...changes,
+            modified_by_id: this.identities.user().id,
+            modified_on: this.now().toISOString(),
+        };
+    }
+}

package/src/platform/security/source-access.ts

@@ -0,0 +1,148 @@
+import { spendContext } from "../../core/context.js";
+import { dataDepthMax } from "../../core/limits.js";
+import type { ExecutionContext } from "../../core/types.js";
+import type {
+    HarnessStorage,
+    ItemTypeDefinition,
+    StorageValue,
+    StoredItem,
+} from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+import { recordKey } from "../references/catalog.js";
+
+interface PermissionSource {
+    readonly definition: ItemTypeDefinition;
+    readonly record: StoredItem;
+}
+
+/** Static preflight and runtime actions enforce the same metadata contract. */
+export function sourceAccessEnabled(
+    definition: Pick<ItemTypeDefinition, "name" | "isRelationship" | "source">,
+    value: StorageValue | undefined,
+): boolean {
+    if (value !== undefined && value !== null && !["0", "1"].includes(String(value))) {
+        throw new PlatformError(
+            "InvalidSourceAccess",
+            `Invalid use_src_access on '${definition.name}'.`,
+            definition.source ? { source: definition.source } : undefined,
+        );
+    }
+
+    if (String(value ?? "0") === "1" && !definition.isRelationship) {
+        throw new PlatformError(
+            "UnsupportedSourceAccess",
+            `Source access requires a relationship ItemType; '${definition.name}' is not one.`,
+            definition.source ? { source: definition.source } : undefined,
+        );
+    }
+
+    return String(value ?? "0") === "1";
+}
+
+/** Resolve stored source generations without invoking business get hooks. */
+export class SourceAccess {
+    private readonly types = new WeakMap<
+        ExecutionContext,
+        ReadonlyMap<string, ItemTypeDefinition>
+    >();
+
+    constructor(private readonly storage: HarnessStorage) {}
+
+    inherited(definition: ItemTypeDefinition): boolean {
+        const value = this.storage.getCatalogEntry("ItemType", definition.id)?.properties
+            .use_src_access;
+
+        return sourceAccessEnabled(definition, value);
+    }
+
+    resolve(
+        definition: ItemTypeDefinition,
+        record: StoredItem,
+        context: ExecutionContext,
+    ): PermissionSource {
+        let current = { definition, record };
+
+        if (!this.inherited(definition)) {
+            return current;
+        }
+
+        const visited = new Set<string>();
+
+        while (this.inherited(current.definition)) {
+            spendContext(context);
+            const key = recordKey(current.record);
+
+            if (visited.has(key)) {
+                throw new PlatformError(
+                    "SourceAccessCycle",
+                    `Source permissions form a cycle at '${current.record.type}:${current.record.id}'.`,
+                    current.definition.source ? { source: current.definition.source } : undefined,
+                );
+            }
+
+            if (visited.size >= dataDepthMax) {
+                throw new PlatformError(
+                    "ProtocolLimit",
+                    "Source permissions exceed their depth limit.",
+                );
+            }
+
+            visited.add(key);
+            current = this.owner(current.definition, current.record.properties, context);
+        }
+
+        return current;
+    }
+
+    owner(
+        relationship: ItemTypeDefinition,
+        values: Readonly<Record<string, StorageValue>>,
+        context: ExecutionContext,
+    ): PermissionSource {
+        const source = relationship.properties.find((property) => property.name === "source_id");
+
+        if (!source?.dataSource) {
+            throw new PlatformError(
+                "UnsupportedSourceAccess",
+                `Source access on '${relationship.name}' requires a concrete source ItemType. for_all relationships need source-type resolution.`,
+                relationship.source ? { source: relationship.source } : undefined,
+            );
+        }
+
+        let types = this.types.get(context);
+
+        if (!types) {
+            const definitions = this.storage.listItemTypes();
+            spendContext(context, definitions.length);
+            types = new Map(
+                definitions.map((definition) => [definition.id.toLowerCase(), definition]),
+            );
+            this.types.set(context, types);
+        }
+
+        spendContext(context);
+        const definition =
+            source.dataType === "item" ? types.get(source.dataSource.toLowerCase()) : undefined;
+        const id = values.source_id;
+
+        if (!definition || typeof id !== "string" || !id) {
+            throw new PlatformError(
+                "InvalidSourceAccess",
+                `Relationship '${relationship.name}' requires a typed source_id to resolve its permissions.`,
+                relationship.source ? { source: relationship.source } : undefined,
+            );
+        }
+
+        const record = this.storage.getItem(definition.name, id);
+
+        if (!record) {
+            throw new PlatformError(
+                "MissingSourceItem",
+                `Permission source '${definition.name}:${id}' for '${relationship.name}' is missing.`,
+                relationship.source ? { source: relationship.source } : undefined,
+            );
+        }
+
+        return { definition, record };
+    }
+}

package/src/platform/security/source-inheritance.ts

@@ -0,0 +1,134 @@
+import { assertActiveContext, spendContext } from "../../core/context.js";
+import { dataNodesMax } from "../../core/limits.js";
+import type { ExecutionContext } from "../../core/types.js";
+import type { HarnessStorage, StorageValue, StoredItem } from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+import { recordKey } from "../references/catalog.js";
+import type { PlatformTrace } from "../trace.js";
+import { InheritedRelationships } from "./inherited-relationships.js";
+import type { ItemPermissions } from "./permissions.js";
+import type { SourceAccess } from "./source-access.js";
+
+const inheritedFields = ["permission_id", "owned_by_id", "managed_by_id", "team_id"];
+
+/** Audit fields belong to the relationship; these four fields inherit from its source. */
+export function inheritedSecurity(source: StoredItem): Record<string, StorageValue> {
+    const values: Record<string, StorageValue> = {};
+
+    for (const name of inheritedFields) {
+        values[name] = source.properties[name] ?? null;
+    }
+
+    return values;
+}
+
+/** Native ACL propagation is a platform write in the original action's transaction. */
+export class SourceInheritance {
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly sources: SourceAccess,
+        private readonly trace: PlatformTrace,
+        private readonly permissions: ItemPermissions,
+    ) {}
+
+    changed(before: StoredItem, after: StoredItem, context: ExecutionContext): void {
+        const fields = inheritedFields.filter(
+            (name) => (before.properties[name] ?? null) !== (after.properties[name] ?? null),
+        );
+
+        if (fields.length === 0) {
+            return;
+        }
+
+        const definition = this.storage.getItemType(after.type);
+
+        if (!definition) {
+            throw new PlatformError(
+                "MissingItemType",
+                `Permission source '${after.type}' has no schema.`,
+            );
+        }
+
+        const inherited = this.permissions.sourceProperties(definition, after, context);
+        const changes: Record<string, StorageValue> = {
+            permission_id: inherited.permission_id ?? null,
+        };
+
+        for (const name of fields) {
+            changes[name] = after.properties[name] ?? null;
+        }
+
+        this.propagate(after, changes, context);
+    }
+
+    private propagate(
+        source: StoredItem,
+        changes: Readonly<Record<string, StorageValue>>,
+        context: ExecutionContext,
+    ): void {
+        const pending = [source];
+        const visited = new Set<string>();
+        const relationships = new InheritedRelationships(this.storage, this.sources, context);
+
+        while (pending.length > 0) {
+            spendContext(context);
+            const parent = pending.pop();
+
+            if (!parent || visited.size >= dataNodesMax) {
+                throw new PlatformError(
+                    "ProtocolLimit",
+                    "Inherited permissions exceed their graph limit.",
+                );
+            }
+
+            const key = recordKey(parent);
+
+            if (visited.has(key)) {
+                throw new PlatformError(
+                    "SourceAccessCycle",
+                    "Inherited permissions contain a cycle.",
+                );
+            }
+
+            visited.add(key);
+
+            for (const child of relationships.children(parent)) {
+                if (pending.length >= dataNodesMax) {
+                    throw new PlatformError(
+                        "ProtocolLimit",
+                        "Inherited permissions exceed their pending graph limit.",
+                    );
+                }
+
+                pending.push(this.update(child, changes, context));
+            }
+        }
+    }
+
+    private update(
+        before: StoredItem,
+        changes: Readonly<Record<string, StorageValue>>,
+        context: ExecutionContext,
+    ): StoredItem {
+        if (Object.entries(changes).every(([name, value]) => before.properties[name] === value)) {
+            return before;
+        }
+
+        assertActiveContext(context);
+        this.storage.updateItem(before.type, before.id, changes);
+        const after = this.storage.getItem(before.type, before.id);
+
+        if (!after) {
+            throw new Error("Permission propagation must retain its relationship.");
+        }
+
+        this.trace.record(context, {
+            kind: "mutation",
+            name: "inherit-permissions",
+            before,
+            after,
+        });
+
+        return after;
+    }
+}

package/src/platform/security/system-identities.ts

@@ -0,0 +1,16 @@
+import { baselineEntries } from "../../baseline/catalog.js";
+
+const identities = new Map(
+    baselineEntries
+        .filter((entry) => entry.type === "Identity")
+        .map((entry) => [String(entry.properties.name), entry.id]),
+);
+
+/** Virtual roles are identified by genuine standard IDs, even if their display names change. */
+export function systemIdentity(id: string, name: string): boolean {
+    return id.toLowerCase() === identities.get(name)?.toLowerCase();
+}
+
+export function systemIdentityId(name: string): string | undefined {
+    return identities.get(name);
+}

package/src/platform/security/teams.ts

@@ -0,0 +1,100 @@
+import { spendContext } from "../../core/context.js";
+import type { ExecutionContext } from "../../core/types.js";
+import type { HarnessStorage, StoredItem } from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+import { systemIdentity } from "./system-identities.js";
+
+const standardRoles = ["Team", "Team Manager", "Team Member", "Team Guest"];
+
+/** One synchronous permission check owns its membership snapshot; actions never share it. */
+export class TeamRoles {
+    private memberships: ReadonlyMap<string, ReadonlySet<string>> | undefined;
+
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly identities: ReadonlySet<string>,
+        private readonly context: ExecutionContext,
+    ) {}
+
+    matches(roleId: string, record: StoredItem): boolean {
+        if (!this.isRole(roleId)) {
+            return false;
+        }
+
+        const teamId = this.teamId(record);
+
+        if (!teamId) {
+            return false;
+        }
+
+        const roles = this.memberRoles().get(teamId.toLowerCase());
+
+        // The standard Team Identity represents membership in any role, including no role.
+        return Boolean(
+            roles && (systemIdentity(roleId, "Team") || roles.has(roleId.toLowerCase())),
+        );
+    }
+
+    private isRole(id: string): boolean {
+        if (standardRoles.some((name) => systemIdentity(id, name))) {
+            return true;
+        }
+
+        const identity = this.storage.getItem("Identity", id);
+
+        return String(identity?.properties.classification ?? "").toLowerCase() === "team";
+    }
+
+    private teamId(record: StoredItem): string | undefined {
+        const id = record.properties.team_id;
+
+        if (id === undefined || id === null || id === "") {
+            return undefined;
+        }
+
+        const source = this.storage.getItemType(record.type)?.source;
+
+        if (typeof id !== "string") {
+            throw new PlatformError(
+                "InvalidTeamReference",
+                `Item '${record.type}:${record.id}' requires a Team ID in team_id.`,
+                source ? { source } : undefined,
+            );
+        }
+
+        if (!this.storage.getItem("Team", id)) {
+            throw new PlatformError(
+                "MissingTeam",
+                `Import Team '${id}' before checking roles on '${record.type}:${record.id}'.`,
+                source ? { source } : undefined,
+            );
+        }
+
+        return id;
+    }
+
+    private memberRoles(): ReadonlyMap<string, ReadonlySet<string>> {
+        if (this.memberships) {
+            return this.memberships;
+        }
+
+        const memberships = new Map<string, Set<string>>();
+
+        for (const member of this.storage.listItems("Team Identity")) {
+            spendContext(this.context);
+
+            if (!this.identities.has(String(member.properties.related_id).toLowerCase())) {
+                continue;
+            }
+
+            const teamId = String(member.properties.source_id).toLowerCase();
+            const roles = memberships.get(teamId) ?? new Set<string>();
+            roles.add(String(member.properties.team_role ?? "").toLowerCase());
+            memberships.set(teamId, roles);
+        }
+
+        this.memberships = memberships;
+
+        return memberships;
+    }
+}