@tinycloud/operations 0.1.0-beta.1

package/dist/artifacts.d.ts

@@ -0,0 +1,391 @@
+import { PermissionEntry } from '@tinycloud/sdk-core';
+import { z } from 'zod';
+import { T as TinyCloudPosture, O as OperationOperatorType } from './contract-mCY8LFFI.js';
+
+/**
+ * A capability in the canonical form persisted in a v1 request artifact.
+ *
+ * The SDK remains the semantic authority for containment. This module only
+ * establishes deterministic exact identity for persistence and display.
+ */
+type CanonicalPermissionEntry = Readonly<PermissionEntry>;
+interface AuthorityEvaluation {
+    readonly satisfied: boolean;
+    readonly missing: readonly CanonicalPermissionEntry[];
+}
+/**
+ * Operation-owned space resolution. The SDK's general capability evaluator
+ * intentionally preserves its historical short/full-space compatibility; the
+ * operation kernel supplies this narrower resolver when a space identifies a
+ * remote owner's resource.
+ */
+type OperationSpaceResolver = (space: string) => string;
+/**
+ * Evaluates required authority with the SDK's public subset primitive.
+ *
+ * In particular, this intentionally does not implement matching rules or
+ * manufacture wildcards. A wildcard can cover a requirement only when it was
+ * already present in the supplied granted authority and the SDK says so.
+ */
+declare function evaluateAuthority(granted: readonly PermissionEntry[], required: readonly PermissionEntry[]): AuthorityEvaluation;
+
+/** The shared wire schema for SDK PermissionEntry values, including signed ReCap caveats. */
+declare const PermissionEntrySchema: z.ZodObject<{
+    service: z.ZodString;
+    space: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    actions: z.ZodArray<z.ZodString, "many">;
+    caveats: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
+    skipPrefix: z.ZodOptional<z.ZodBoolean>;
+    expiry: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    service: string;
+    path: string;
+    actions: string[];
+    space?: string | undefined;
+    caveats?: Record<string, unknown>[] | undefined;
+    skipPrefix?: boolean | undefined;
+    expiry?: string | undefined;
+    description?: string | undefined;
+}, {
+    service: string;
+    path: string;
+    actions: string[];
+    space?: string | undefined;
+    caveats?: Record<string, unknown>[] | undefined;
+    skipPrefix?: boolean | undefined;
+    expiry?: string | undefined;
+    description?: string | undefined;
+}>;
+declare const LegacyPermissionRequestArtifactSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"tinycloud.auth.request">;
+    version: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sessionDid: z.ZodString;
+    requested: z.ZodArray<z.ZodObject<{
+        service: z.ZodString;
+        space: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        actions: z.ZodArray<z.ZodString, "many">;
+        caveats: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
+        skipPrefix: z.ZodOptional<z.ZodBoolean>;
+        expiry: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }, {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }>, "many">;
+    requestedExpiry: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strict", z.ZodTypeAny, {
+    kind: "tinycloud.auth.request";
+    version: 1;
+    requestId: string;
+    sessionDid: string;
+    requested: {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }[];
+    requestedExpiry?: string | number | undefined;
+}, {
+    kind: "tinycloud.auth.request";
+    version: 1;
+    requestId: string;
+    sessionDid: string;
+    requested: {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }[];
+    requestedExpiry?: string | number | undefined;
+}>;
+/** Canonical wire-format v1 request retained for CLI and OpenKey compatibility. */
+declare const PermissionRequestArtifactSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"tinycloud.auth.request">;
+    version: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    createdAt: z.ZodString;
+    profile: z.ZodString;
+    posture: z.ZodEnum<["owner-openkey", "delegate-session", "local-owner-key", "unauthenticated"]>;
+    operatorType: z.ZodEnum<["human", "agent"]>;
+    host: z.ZodString;
+    sessionDid: z.ZodString;
+    ownerDid: z.ZodOptional<z.ZodString>;
+    spaceId: z.ZodOptional<z.ZodString>;
+    requestedExpiry: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    requested: z.ZodArray<z.ZodObject<{
+        service: z.ZodString;
+        space: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        actions: z.ZodArray<z.ZodString, "many">;
+        caveats: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
+        skipPrefix: z.ZodOptional<z.ZodBoolean>;
+        expiry: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }, {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }>, "many">;
+    command: z.ZodOptional<z.ZodObject<{
+        argv: z.ZodArray<z.ZodString, "many">;
+        cwd: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        argv: string[];
+        cwd: string;
+    }, {
+        argv: string[];
+        cwd: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    kind: "tinycloud.auth.request";
+    version: 1;
+    requestId: string;
+    sessionDid: string;
+    requested: {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }[];
+    host: string;
+    createdAt: string;
+    profile: string;
+    posture: "owner-openkey" | "delegate-session" | "local-owner-key" | "unauthenticated";
+    operatorType: "human" | "agent";
+    requestedExpiry?: string | number | undefined;
+    spaceId?: string | undefined;
+    ownerDid?: string | undefined;
+    command?: {
+        argv: string[];
+        cwd: string;
+    } | undefined;
+}, {
+    kind: "tinycloud.auth.request";
+    version: 1;
+    requestId: string;
+    sessionDid: string;
+    requested: {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }[];
+    host: string;
+    createdAt: string;
+    profile: string;
+    posture: "owner-openkey" | "delegate-session" | "local-owner-key" | "unauthenticated";
+    operatorType: "human" | "agent";
+    requestedExpiry?: string | number | undefined;
+    spaceId?: string | undefined;
+    ownerDid?: string | undefined;
+    command?: {
+        argv: string[];
+        cwd: string;
+    } | undefined;
+}>;
+/** Canonical structured v1 delegation import accepted by the auth operation. */
+declare const DelegationImportArtifactSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"tinycloud.auth.delegation">;
+    version: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    delegationCid: z.ZodOptional<z.ZodString>;
+    delegation: z.ZodType<Record<string, unknown>, z.ZodTypeDef, Record<string, unknown>>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        service: z.ZodString;
+        space: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        actions: z.ZodArray<z.ZodString, "many">;
+        caveats: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
+        skipPrefix: z.ZodOptional<z.ZodBoolean>;
+        expiry: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }, {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }>, "many">>;
+    expiry: z.ZodOptional<z.ZodString>;
+    prompted: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    kind: "tinycloud.auth.delegation";
+    version: 1;
+    requestId: string;
+    delegation: Record<string, unknown>;
+    expiry?: string | undefined;
+    delegationCid?: string | undefined;
+    permissions?: {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }[] | undefined;
+    prompted?: boolean | undefined;
+}, {
+    kind: "tinycloud.auth.delegation";
+    version: 1;
+    requestId: string;
+    delegation: Record<string, unknown>;
+    expiry?: string | undefined;
+    delegationCid?: string | undefined;
+    permissions?: {
+        service: string;
+        path: string;
+        actions: string[];
+        space?: string | undefined;
+        caveats?: Record<string, unknown>[] | undefined;
+        skipPrefix?: boolean | undefined;
+        expiry?: string | undefined;
+        description?: string | undefined;
+    }[] | undefined;
+    prompted?: boolean | undefined;
+}>;
+type PermissionRequestArtifact = z.infer<typeof PermissionRequestArtifactSchema>;
+type DelegationImportArtifact = z.infer<typeof DelegationImportArtifactSchema>;
+/** The minimal public node-sdk request shape accepted by the legacy reader. */
+type LegacyPermissionRequestArtifact = z.infer<typeof LegacyPermissionRequestArtifactSchema>;
+type ArtifactClock = () => Date;
+type RequestIdSource = () => string;
+/** Invocation-owned values used to safely complete a legacy request record. */
+interface LegacyRequestContext {
+    readonly profile: string;
+    readonly host: string;
+    readonly sessionDid: string;
+    readonly posture: TinyCloudPosture;
+    readonly operatorType: OperationOperatorType;
+    readonly ownerDid?: string;
+    readonly spaceId?: string;
+    readonly now?: Date;
+}
+interface PermissionRequestIdentityInput {
+    readonly profile: string;
+    readonly sessionDid: string;
+    readonly host: string;
+    readonly missing: readonly PermissionEntry[];
+}
+interface BuildPermissionRequestArtifactInput extends PermissionRequestIdentityInput {
+    readonly posture: TinyCloudPosture;
+    readonly operatorType: OperationOperatorType;
+    readonly ownerDid?: string;
+    readonly spaceId?: string;
+    readonly requestedExpiry?: string | number;
+    readonly command?: {
+        readonly argv: readonly string[];
+        readonly cwd: string;
+    };
+    readonly now?: ArtifactClock;
+    readonly createRequestId?: RequestIdSource;
+}
+interface CreateOrReusePermissionRequestInput extends BuildPermissionRequestArtifactInput {
+    readonly granted: readonly PermissionEntry[];
+    /** Owner-aware identity resolver used by registered operation callers. */
+    readonly resolveSpace?: OperationSpaceResolver;
+    readonly replace?: boolean;
+}
+type PermissionRequestResolution = Readonly<{
+    status: "satisfied";
+    reused: false;
+}> | Readonly<{
+    status: "created";
+    reused: boolean;
+    request: PermissionRequestArtifact;
+}>;
+/** Parses a request artifact without accepting a newer wire format as v1. */
+declare function validatePermissionRequestArtifact(value: unknown): PermissionRequestArtifact;
+/** Parses a structured active-session import artifact without accepting a newer wire format as v1. */
+declare function validateDelegationImportArtifact(value: unknown): DelegationImportArtifact;
+declare function isPermissionRequestArtifact(value: unknown): value is PermissionRequestArtifact;
+declare function isDelegationImportArtifact(value: unknown): value is DelegationImportArtifact;
+/**
+ * Stable exact identity used only for request reuse. It binds a request to its
+ * selected profile, active session DID, host, and canonical missing subset.
+ */
+declare function createPermissionRequestIdentity(input: PermissionRequestIdentityInput): string;
+/** Builds an on-disk-compatible v1 record. Omitted values stay omitted. */
+declare function buildPermissionRequestArtifact(input: BuildPermissionRequestArtifactInput): PermissionRequestArtifact;
+/** Reads only valid canonical v1 records and refuses malformed stored artifacts. */
+declare function listPermissionRequests(profile: string, context?: LegacyRequestContext): Promise<PermissionRequestArtifact[]>;
+declare function findPermissionRequest(profile: string, requestId: string, identity: Pick<PermissionRequestIdentityInput, "sessionDid" | "host"> & Partial<Omit<LegacyRequestContext, "profile" | "host" | "sessionDid">>): Promise<PermissionRequestArtifact | null>;
+/**
+ * Atomically returns the newest identical unresolved request, or writes a new
+ * v1 record. Retention, stale-session pruning, covered-record pruning, and
+ * partial-grant supersession all happen in the same existing profile lock.
+ */
+declare function createOrReusePermissionRequest(input: CreateOrReusePermissionRequestInput): Promise<PermissionRequestResolution>;
+interface PrunePermissionRequestsInput {
+    readonly profile: string;
+    readonly sessionDid: string;
+    readonly granted: readonly PermissionEntry[];
+    readonly resolveSpace?: OperationSpaceResolver;
+    readonly now: Date;
+}
+/** Pure retention policy used by the locked persistence operation. */
+declare function prunePermissionRequests(records: readonly PermissionRequestArtifact[], input: PrunePermissionRequestsInput): PermissionRequestArtifact[];
+
+export { type ArtifactClock, type BuildPermissionRequestArtifactInput, type CreateOrReusePermissionRequestInput, type DelegationImportArtifact, DelegationImportArtifactSchema, type LegacyPermissionRequestArtifact, type LegacyRequestContext, PermissionEntrySchema, type PermissionRequestArtifact, PermissionRequestArtifactSchema, type PermissionRequestIdentityInput, type PermissionRequestResolution, type PrunePermissionRequestsInput, type RequestIdSource, buildPermissionRequestArtifact, createOrReusePermissionRequest, createPermissionRequestIdentity, evaluateAuthority, findPermissionRequest, isDelegationImportArtifact, isPermissionRequestArtifact, listPermissionRequests, prunePermissionRequests, validateDelegationImportArtifact, validatePermissionRequestArtifact };