@smthrs/kernel 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/GrantStore.d.ts

@@ -0,0 +1,270 @@
+/**
+ * In-memory capability grants with an attended Deferred request lifecycle.
+ *
+ * Governing design:
+ * `docs/specs/Concepts/Permission Kernel.md` and
+ * `docs/specs/Concepts/Trust Granularity.md`.
+ *
+ * @since 1.0.0-rc.0
+ */
+import { type Capability, CapabilityPattern, type EffectTier } from "@smthrs/capability/Capability";
+import { GrantStoreError, type PermissionDenied, type PermissionRequired, Rule } from "@smthrs/capability/Permission";
+import { Context, Effect, Layer, type Scope } from "effect";
+import { type CapabilitySet } from "./CapabilitySet.ts";
+import { type GrantEvent } from "./GrantEvent.ts";
+import { Workspace } from "./Workspace.ts";
+/**
+ * A capability request waiting for an attended reply.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface PendingRequest {
+    readonly requestId: string;
+    readonly capability: Capability;
+    readonly tier: EffectTier;
+    readonly meta: Record<string, unknown>;
+}
+/**
+ * A resolution supplied by an attended permission surface.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Resolution = "once" | "run" | "remembered" | "deny";
+/**
+ * Scope and plan identity for a bulk envelope approval.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface EnvelopeGrantOptions {
+    readonly planDigest: string;
+    readonly patterns: ReadonlyArray<CapabilityPattern>;
+    readonly scope?: "run" | "remembered" | undefined;
+}
+/** A policy rule and the authority captured when it was granted.
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export interface PolicyRule {
+    readonly rule: Rule;
+    readonly ceiling: Pick<CapabilitySet, "groups">;
+}
+/** Atomic ordered policy snapshot, bounded by the calling fiber.
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export interface Policy {
+    readonly groups: ReadonlyArray<ReadonlyArray<PolicyRule>>;
+    readonly ceiling: CapabilitySet;
+}
+/** A conservative snapshot for services that expose no durable authority.
+ * @category constructors
+ * @since 1.0.0-rc.1
+ */
+export declare const emptyPolicy: Effect.Effect<Policy>;
+/** Operations exposed by the grant store.
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Service {
+    readonly policy: Effect.Effect<Policy, GrantStoreError>;
+    readonly check: (capability: Capability, meta?: Record<string, unknown>) => Effect.Effect<void, PermissionRequired | PermissionDenied | GrantStoreError>;
+    readonly reply: (requestId: string, resolution: Resolution, pattern?: CapabilityPattern) => Effect.Effect<void, GrantStoreError>;
+    readonly list: Effect.Effect<ReadonlyArray<PendingRequest>>;
+    readonly grantEnvelope: (options: EnvelopeGrantOptions) => Effect.Effect<void, GrantStoreError>;
+}
+declare const GrantStore_base: Context.ServiceClass<GrantStore, "@smthrs/kernel/GrantStore", Service>;
+/**
+ * Service key for permission decisions and attended grant requests.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export declare class GrantStore extends GrantStore_base {
+}
+/**
+ * A hook that durably records a grant decision before it becomes active.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Persist = (event: GrantEvent) => Effect.Effect<void, GrantStoreError>;
+/**
+ * Configuration for an in-memory grant store.
+ *
+ * A nested `rules` value is also accepted by the journal adapter: its first
+ * ruleset is configured policy and subsequent rulesets are replayed remembered
+ * grants.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface MakeOptions {
+    readonly attended?: boolean | undefined;
+    readonly rules?: ReadonlyArray<Rule> | ReadonlyArray<ReadonlyArray<Rule>> | undefined;
+    /** Bare rules use the constructor ceiling; captured groups intersect it. */
+    readonly runRules?: ReadonlyArray<Rule | {
+        readonly rule: Rule;
+        readonly ceiling: ReadonlyArray<ReadonlyArray<CapabilityPattern>>;
+    }> | undefined;
+    readonly envelope?: EnvelopeGrantOptions | undefined;
+    /**
+     * {@link envelopeSignature} values of envelopes that are already durable —
+     * typically replayed from a journal. A construction or runtime envelope
+     * matching a seeded signature still activates its rules but is not
+     * persisted again.
+     */
+    readonly envelopeSignatures?: ReadonlyArray<string> | undefined;
+    readonly runId?: string | undefined;
+    readonly planDigest?: string | undefined;
+    readonly persist?: Persist | undefined;
+}
+/**
+ * Maximum policy rules retained by one store.
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumRules = 1024;
+/**
+ * Maximum predicates in one approval envelope.
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumEnvelopePatterns = 256;
+/**
+ * Maximum permission requests parked at once.
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumPendingRequests = 1024;
+/**
+ * Maximum nesting depth of permission metadata.
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumMetadataDepth = 16;
+/**
+ * Maximum members across one permission metadata graph.
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumMetadataMembers = 1024;
+/**
+ * Maximum encoded bytes retained for one metadata value.
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumMetadataBytes: number;
+/**
+ * Maximum encoded bytes persisted for one grant event.
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumEventBytes: number;
+/**
+ * Maximum milliseconds one grant journal write may take before its reply or
+ * envelope admission fails with `journal_failed`. Journal writes never hold
+ * the store's mutation permit, so a slow write stalls only the admission that
+ * issued it.
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumPersistMillis = 30000;
+/**
+ * Maximum length of a run, plan, request, or signature identity.
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumIdentityLength = 4096;
+/**
+ * Maximum capability resource length enforced by the capability vocabulary.
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumCapabilityResourceLength = 4096;
+/**
+ * Canonicalizes an envelope pattern list: duplicate predicates collapse to
+ * their first occurrence and the survivors sort by their formatted identity.
+ *
+ * An envelope is a *set* of predicates, so two envelopes listing the same
+ * predicates in a different order or multiplicity are the same approval. Every
+ * envelope is canonicalized before it is persisted or compared, which makes
+ * envelope idempotency structural rather than dependent on caller discipline.
+ *
+ * The ordering is the code-unit sort of `format(pattern)` — the one renderer
+ * for capability identity. RFC 8785 canonical JSON (`@smthrs/canonical`)
+ * was considered and does not fit: it canonicalizes object keys but preserves
+ * array order as semantic, and the ordering that matters here is exactly the
+ * pattern-array order.
+ *
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export declare const canonicalEnvelopePatterns: (patterns: ReadonlyArray<CapabilityPattern>) => ReadonlyArray<CapabilityPattern>;
+/**
+ * Computes the canonical identity of an envelope approval.
+ *
+ * Two envelopes with the same plan digest, scope, and predicate set produce
+ * the same signature regardless of pattern order or repetition. The signature
+ * is how the store, and journal replay above it, recognise an envelope that
+ * is already durable. It is `sha256:` followed by 64 lowercase hex digits.
+ *
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export declare const envelopeSignature: (planDigest: string, scope: "run" | "remembered", patterns: ReadonlyArray<CapabilityPattern>) => string;
+/**
+ * Checks that a request-scoped grant cannot authorize a different action or a
+ * more dangerous effect tier than the request displayed to the user. A
+ * wildcard-bearing pattern identical to the resource is ambiguous because the
+ * grammar has no escape, so its wildcard reading would silently widen access.
+ *
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export declare const isValidGrantPattern: (pattern: CapabilityPattern, capability: Capability, tier: EffectTier, workspaceRoot: string) => boolean;
+/**
+ * Checks that a bulk envelope pattern preserves exact action and filesystem
+ * effect-tier boundaries.
+ *
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export declare const isValidEnvelopePattern: (pattern: CapabilityPattern, workspaceRoot: string) => boolean;
+/**
+ * Builds an in-memory grant store.
+ *
+ * Attended stores suspend an asking fiber on a request-local `Deferred`.
+ * Unattended stores fail immediately with `PermissionRequired`. The returned
+ * service is scoped: closing its scope rejects every waiter and clears the
+ * pending map.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const make: (options?: MakeOptions) => Effect.Effect<Service, GrantStoreError, Scope.Scope | Workspace>;
+/**
+ * Provides a scoped in-memory grant store.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layer: (options?: MakeOptions) => Layer.Layer<GrantStore, GrantStoreError, Workspace>;
+/**
+ * An allow-all grant store.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const makeNoop: Service;
+/**
+ * Provides the allow-all grant store.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerNoop: Layer.Layer<GrantStore>;
+export {};
+//# sourceMappingURL=GrantStore.d.ts.map

package/dist/esm/GrantStore.d.ts.map

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