@tinycloud/operations 0.4.0-beta.9 → 0.4.0

package/dist/{contract-CjuEjE-M.d.cts → contract-BRwWJpPs.d.cts}

@@ -1,4 +1,4 @@
-declare const OPERATION_ERROR_CODES: readonly ["INPUT_INVALID", "OPERATION_NOT_FOUND", "OPERATION_VERSION_UNSUPPORTED", "PROFILE_NOT_FOUND", "PROFILE_POSTURE_NOT_ALLOWED", "PROFILE_OWNER_OPT_IN_REQUIRED", "AUTH_REQUIRED", "PERMISSION_DENIED", "SESSION_NOT_FOUND", "PERMISSION_HINT_INVALID", "DELEGATION_ARTIFACT_INVALID", "DELEGATION_EXPIRED", "DELEGATION_AUDIENCE_MISMATCH", "DELEGATION_HOST_MISMATCH", "DELEGATION_REJECTED", "ENCRYPTION_NETWORK_UNRESOLVED", "NODE_UNREACHABLE", "NODE_ERROR", "KV_NOT_FOUND", "KV_PRECONDITION_FAILED", "KV_CONFLICT", "KV_RESPONSE_TOO_LARGE", "SQL_QUERY_INVALID", "SQL_EXECUTION_FAILED", "SQL_RESULT_LIMIT_EXCEEDED", "SQL_VALUE_UNSAFE", "SECRET_READ_FAILED", "SECRET_DECRYPT_FAILED", "OUTPUT_INVALID", "INTERNAL_ERROR"];
+declare const OPERATION_ERROR_CODES: readonly ["INPUT_INVALID", "OPERATION_NOT_FOUND", "OPERATION_VERSION_UNSUPPORTED", "PROFILE_NOT_FOUND", "PROFILE_POSTURE_NOT_ALLOWED", "PROFILE_OWNER_OPT_IN_REQUIRED", "AUTH_REQUIRED", "PERMISSION_DENIED", "SESSION_NOT_FOUND", "PERMISSION_HINT_INVALID", "DELEGATION_ARTIFACT_INVALID", "DELEGATION_EXPIRED", "DELEGATION_AUDIENCE_MISMATCH", "DELEGATION_HOST_MISMATCH", "DELEGATION_REJECTED", "ENCRYPTION_NETWORK_UNRESOLVED", "NODE_UNREACHABLE", "NODE_ERROR", "STORAGE_QUOTA_EXCEEDED", "KV_NOT_FOUND", "KV_PRECONDITION_FAILED", "KV_CONFLICT", "KV_RESPONSE_TOO_LARGE", "SQL_QUERY_INVALID", "SQL_EXECUTION_FAILED", "SQL_RESULT_LIMIT_EXCEEDED", "SQL_VALUE_UNSAFE", "SECRET_READ_FAILED", "SECRET_DECRYPT_FAILED", "OUTPUT_INVALID", "INTERNAL_ERROR"];
 type OperationErrorCode = (typeof OPERATION_ERROR_CODES)[number];
 interface OperationError {
     readonly code: OperationErrorCode;
@@ -25,6 +25,24 @@ interface OperationContextSummary {
     readonly ownerDid?: string;
     readonly space?: string;
 }
+/**
+ * Why a stored grant was not used. A fixed vocabulary: diagnostics never
+ * carry exception text, node responses, URLs or other stored transport data.
+ * `unbound`: the record has no valid request binding where one is required;
+ * `outside_request`: its signed authority exceeds its binding.
+ */
+declare const STORED_GRANT_SKIP_REASONS: readonly ["malformed", "unbound", "outside_request", "host_mismatch", "expired", "cid_mismatch", "authority_invalid", "proof_missing", "proof_invalid", "owner_mismatch", "audience_mismatch", "resources_mismatch", "unsupported", "activation_rejected", "invalid"];
+type StoredGrantSkipReason = typeof STORED_GRANT_SKIP_REASONS[number];
+/**
+ * A non-fatal diagnostic attached to a result. `STORED_GRANT_SKIPPED`: a
+ * stored grant failed validation and gave no authority; `grantCid` is present
+ * only when the stored CID is the CID of the stored authorization bytes.
+ */
+interface OperationWarning {
+    readonly code: "STORED_GRANT_SKIPPED";
+    readonly reason: StoredGrantSkipReason;
+    readonly grantCid?: string;
+}
 /**
  * Capability details are finalized by the authority/artifacts increment. The
  * kernel intentionally preserves them as canonical operation-owned data.
@@ -58,6 +76,7 @@ interface OperationOkResult<O> {
     readonly operation: OperationRef;
     readonly context: OperationContextSummary;
     readonly output: O;
+    readonly warnings?: readonly OperationWarning[];
 }
 interface OperationAuthorityRequiredResult {
     readonly status: "authority_required";
@@ -67,6 +86,7 @@ interface OperationAuthorityRequiredResult {
     readonly request: PermissionRequestArtifact;
     readonly approval: ApprovalAction;
     readonly retry: RetryDescriptor;
+    readonly warnings?: readonly OperationWarning[];
 }
 interface OperationSetupRequiredResult {
     readonly status: "setup_required";
@@ -74,12 +94,14 @@ interface OperationSetupRequiredResult {
     readonly context: OperationContextSummary;
     readonly setup: SetupAction;
     readonly retry: RetryDescriptor;
+    readonly warnings?: readonly OperationWarning[];
 }
 interface OperationErrorResult {
     readonly status: "error";
     readonly operation: OperationRef;
     readonly context: OperationContextSummary;
     readonly error: OperationError;
+    readonly warnings?: readonly OperationWarning[];
 }
 type OperationResult<O> = OperationOkResult<O> | OperationAuthorityRequiredResult | OperationSetupRequiredResult | OperationErrorResult;
 /**
@@ -100,4 +122,4 @@ interface InvocationTarget {
     readonly privateKey?: string;
 }
 
-export type { InvocationTarget as I, OperationOperatorType as O, TinyCloudPosture as T, OperationResult as a, OperationContextSummary as b };
+export type { InvocationTarget as I, OperationOperatorType as O, StoredGrantSkipReason as S, TinyCloudPosture as T, OperationResult as a, OperationContextSummary as b };

package/dist/{contract-CjuEjE-M.d.ts → contract-BRwWJpPs.d.ts}

@@ -1,4 +1,4 @@
-declare const OPERATION_ERROR_CODES: readonly ["INPUT_INVALID", "OPERATION_NOT_FOUND", "OPERATION_VERSION_UNSUPPORTED", "PROFILE_NOT_FOUND", "PROFILE_POSTURE_NOT_ALLOWED", "PROFILE_OWNER_OPT_IN_REQUIRED", "AUTH_REQUIRED", "PERMISSION_DENIED", "SESSION_NOT_FOUND", "PERMISSION_HINT_INVALID", "DELEGATION_ARTIFACT_INVALID", "DELEGATION_EXPIRED", "DELEGATION_AUDIENCE_MISMATCH", "DELEGATION_HOST_MISMATCH", "DELEGATION_REJECTED", "ENCRYPTION_NETWORK_UNRESOLVED", "NODE_UNREACHABLE", "NODE_ERROR", "KV_NOT_FOUND", "KV_PRECONDITION_FAILED", "KV_CONFLICT", "KV_RESPONSE_TOO_LARGE", "SQL_QUERY_INVALID", "SQL_EXECUTION_FAILED", "SQL_RESULT_LIMIT_EXCEEDED", "SQL_VALUE_UNSAFE", "SECRET_READ_FAILED", "SECRET_DECRYPT_FAILED", "OUTPUT_INVALID", "INTERNAL_ERROR"];
+declare const OPERATION_ERROR_CODES: readonly ["INPUT_INVALID", "OPERATION_NOT_FOUND", "OPERATION_VERSION_UNSUPPORTED", "PROFILE_NOT_FOUND", "PROFILE_POSTURE_NOT_ALLOWED", "PROFILE_OWNER_OPT_IN_REQUIRED", "AUTH_REQUIRED", "PERMISSION_DENIED", "SESSION_NOT_FOUND", "PERMISSION_HINT_INVALID", "DELEGATION_ARTIFACT_INVALID", "DELEGATION_EXPIRED", "DELEGATION_AUDIENCE_MISMATCH", "DELEGATION_HOST_MISMATCH", "DELEGATION_REJECTED", "ENCRYPTION_NETWORK_UNRESOLVED", "NODE_UNREACHABLE", "NODE_ERROR", "STORAGE_QUOTA_EXCEEDED", "KV_NOT_FOUND", "KV_PRECONDITION_FAILED", "KV_CONFLICT", "KV_RESPONSE_TOO_LARGE", "SQL_QUERY_INVALID", "SQL_EXECUTION_FAILED", "SQL_RESULT_LIMIT_EXCEEDED", "SQL_VALUE_UNSAFE", "SECRET_READ_FAILED", "SECRET_DECRYPT_FAILED", "OUTPUT_INVALID", "INTERNAL_ERROR"];
 type OperationErrorCode = (typeof OPERATION_ERROR_CODES)[number];
 interface OperationError {
     readonly code: OperationErrorCode;
@@ -25,6 +25,24 @@ interface OperationContextSummary {
     readonly ownerDid?: string;
     readonly space?: string;
 }
+/**
+ * Why a stored grant was not used. A fixed vocabulary: diagnostics never
+ * carry exception text, node responses, URLs or other stored transport data.
+ * `unbound`: the record has no valid request binding where one is required;
+ * `outside_request`: its signed authority exceeds its binding.
+ */
+declare const STORED_GRANT_SKIP_REASONS: readonly ["malformed", "unbound", "outside_request", "host_mismatch", "expired", "cid_mismatch", "authority_invalid", "proof_missing", "proof_invalid", "owner_mismatch", "audience_mismatch", "resources_mismatch", "unsupported", "activation_rejected", "invalid"];
+type StoredGrantSkipReason = typeof STORED_GRANT_SKIP_REASONS[number];
+/**
+ * A non-fatal diagnostic attached to a result. `STORED_GRANT_SKIPPED`: a
+ * stored grant failed validation and gave no authority; `grantCid` is present
+ * only when the stored CID is the CID of the stored authorization bytes.
+ */
+interface OperationWarning {
+    readonly code: "STORED_GRANT_SKIPPED";
+    readonly reason: StoredGrantSkipReason;
+    readonly grantCid?: string;
+}
 /**
  * Capability details are finalized by the authority/artifacts increment. The
  * kernel intentionally preserves them as canonical operation-owned data.
@@ -58,6 +76,7 @@ interface OperationOkResult<O> {
     readonly operation: OperationRef;
     readonly context: OperationContextSummary;
     readonly output: O;
+    readonly warnings?: readonly OperationWarning[];
 }
 interface OperationAuthorityRequiredResult {
     readonly status: "authority_required";
@@ -67,6 +86,7 @@ interface OperationAuthorityRequiredResult {
     readonly request: PermissionRequestArtifact;
     readonly approval: ApprovalAction;
     readonly retry: RetryDescriptor;
+    readonly warnings?: readonly OperationWarning[];
 }
 interface OperationSetupRequiredResult {
     readonly status: "setup_required";
@@ -74,12 +94,14 @@ interface OperationSetupRequiredResult {
     readonly context: OperationContextSummary;
     readonly setup: SetupAction;
     readonly retry: RetryDescriptor;
+    readonly warnings?: readonly OperationWarning[];
 }
 interface OperationErrorResult {
     readonly status: "error";
     readonly operation: OperationRef;
     readonly context: OperationContextSummary;
     readonly error: OperationError;
+    readonly warnings?: readonly OperationWarning[];
 }
 type OperationResult<O> = OperationOkResult<O> | OperationAuthorityRequiredResult | OperationSetupRequiredResult | OperationErrorResult;
 /**
@@ -100,4 +122,4 @@ interface InvocationTarget {
     readonly privateKey?: string;
 }
 
-export type { InvocationTarget as I, OperationOperatorType as O, TinyCloudPosture as T, OperationResult as a, OperationContextSummary as b };
+export type { InvocationTarget as I, OperationOperatorType as O, StoredGrantSkipReason as S, TinyCloudPosture as T, OperationResult as a, OperationContextSummary as b };

package/dist/delegation-binding.cjs

@@ -152,6 +152,7 @@ var delegation_binding_exports = {};
 __export(delegation_binding_exports, {
   BINDING_NOTES: () => BINDING_NOTES,
   activateUnboundCompactImport: () => activateUnboundCompactImport,
+  bindCliGrant: () => bindCliGrant,
   bindingMigrationPath: () => bindingMigrationPath,
   bindingMigrationRecorded: () => bindingMigrationRecorded,
   mergeDelegationsWithoutRequest: () => mergeDelegationsWithoutRequest,
@@ -277,8 +278,17 @@ function canonicalizeRecapCaveats(caveats) {
   }
   return `[${branches.join(",")}]`;
 }
+var EXPLICIT_ONLY_ACTIONS = {
+  "tinycloud.kv/sync": true,
+  "tinycloud.kv/retain": true
+};
+function isExplicitOnlyAction(action) {
+  return Object.prototype.hasOwnProperty.call(EXPLICIT_ONLY_ACTIONS, action);
+}
 function actionContains(grantedAction, requestedAction) {
-  if (grantedAction === "*" || grantedAction === requestedAction) return true;
+  if (grantedAction === requestedAction) return true;
+  if (isExplicitOnlyAction(requestedAction)) return false;
+  if (grantedAction === "*") return true;
   if (!grantedAction.endsWith("/*")) return false;
   const service = grantedAction.slice(0, -2);
   return requestedAction === service || requestedAction.startsWith(`${service}/`);
@@ -580,7 +590,8 @@ async function acquireProfileLock(profile, options) {
   const lockPath = profileLockPath(profile);
   const turnDirectory = profileTurnLockPath(profile);
   const directory = profilePath(profile);
-  await (0, import_promises.mkdir)(directory, { recursive: true, mode: PRIVATE_DIR_MODE });
+  if (options.requireProfile && !await exists(profileConfigPath(profile))) throw new ProfileDeletedError(profile);
+  if (!options.requireProfile) await (0, import_promises.mkdir)(directory, { recursive: true, mode: PRIVATE_DIR_MODE });
   await (0, import_promises.mkdir)((0, import_node_path.dirname)(turnDirectory), { recursive: true, mode: PRIVATE_DIR_MODE });
   for (const path of [tinycloudHomePath(), profilesPath(), directory]) {
     await (0, import_promises.chmod)(path, PRIVATE_DIR_MODE).catch((error) => {
@@ -589,11 +600,15 @@ async function acquireProfileLock(profile, options) {
   }
   const { turn, firstWaitedTurn } = await acquireTurn(profile, turnDirectory, deadline);
   try {
+    if (options.requireProfile && !await exists(profileConfigPath(profile))) {
+      await (0, import_promises.rmdir)(directory).catch(() => void 0);
+      throw new ProfileDeletedError(profile);
+    }
     const deletion = await readJson((0, import_node_path.join)(turnDirectory, "deleted.json")).catch(() => null);
     const deletedWhileWaiting = typeof deletion?.slot === "number" && deletion.slot >= firstWaitedTurn;
     while (true) {
       const token = (0, import_node_crypto.randomUUID)();
-      if (await publishProfileLock(profile, lockPath, token)) {
+      if (await publishProfileLock(profile, lockPath, token, options.requireProfile === true)) {
         return {
           deletedWhileWaiting,
           turnSlot: turn.slot,
@@ -844,12 +859,13 @@ async function collectTurns(profile, turn) {
     }
   }
 }
-async function publishProfileLock(profile, lockPath, token) {
+async function publishProfileLock(profile, lockPath, token, requireProfile) {
   try {
     await (0, import_promises.mkdir)(lockPath, { mode: PRIVATE_DIR_MODE });
   } catch (error) {
     if (isErrno(error, "EEXIST")) return false;
     if (!isErrno(error, "ENOENT")) throw error;
+    if (requireProfile) throw new ProfileDeletedError(profile);
     await (0, import_promises.mkdir)(profilePath(profile), { recursive: true, mode: PRIVATE_DIR_MODE });
     return false;
   }
@@ -1144,6 +1160,25 @@ var DelegationImportArtifactSchema = import_zod.z.object({
 }).strict();
 var DelegationRequestBindingSchema = PermissionRequestArtifactSchema.pick({ requestId: true, requested: true }).strict();
 
+// src/contract.ts
+var STORED_GRANT_SKIP_REASONS = [
+  "malformed",
+  "unbound",
+  "outside_request",
+  "host_mismatch",
+  "expired",
+  "cid_mismatch",
+  "authority_invalid",
+  "proof_missing",
+  "proof_invalid",
+  "owner_mismatch",
+  "audience_mismatch",
+  "resources_mismatch",
+  "unsupported",
+  "activation_rejected",
+  "invalid"
+];
+
 // src/secrets.ts
 var nodeSdk = __toESM(require("@tinycloud/node-sdk"), 1);
 
@@ -1224,11 +1259,13 @@ function invalidSecretInput() {
 // src/delegation-binding.ts
 var REQUEST_ID_PREFIX = {
   migration: "migrated",
-  "unbound-import": "unbound-import"
+  "unbound-import": "unbound-import",
+  "cli-grant": "cli-grant"
 };
 var BINDING_NOTES = {
   migration: "Stored without a request binding before bindings were required. Bound at migration to exactly its own signed capabilities, so replay refuses any delegation in this record that exceeds them.",
-  "unbound-import": "Imported by `tc auth import` without a stored request. Bound to exactly its own signed capabilities, so replay refuses any delegation in this record that exceeds them."
+  "unbound-import": "Imported by `tc auth import` without a stored request. Bound to exactly its own signed capabilities, so replay refuses any delegation in this record that exceeds them.",
+  "cli-grant": "Granted to this CLI by `tc auth request --grant` or a permission escalation, and checked against the request it answered. Bound to exactly its own signed capabilities, so replay refuses any delegation in this record that exceeds them."
 };
 var MIGRATION_LOCK_TIMEOUT_MS = 250;
 function bindingMigrationPath(profile) {
@@ -1253,19 +1290,26 @@ function replayLimit(entry, migrated) {
   if (binding.success) return binding.data.requested;
   return !migrated && kind === "compact" && !("authorityRequest" in entry) ? "signed" : void 0;
 }
-function bindToSignedCapabilities(record, signed, source, recordedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+function bindToRequest(record, requested, source, recordedAt = (/* @__PURE__ */ new Date()).toISOString()) {
   return {
     ...record,
     authorityRequest: DelegationRequestBindingSchema.parse({
       requestId: `${REQUEST_ID_PREFIX[source]}:${record.delegation.cid}`,
-      requested: structuredClone(signed)
+      requested: structuredClone(requested)
     }),
     authorityRequestAudit: { source, recordedAt, note: BINDING_NOTES[source] }
   };
 }
+async function bindCliGrant(node, record, host) {
+  const signed = await signedCapabilities(node, record.delegation, host);
+  if (signed === void 0) {
+    throw new Error("The grant's signed authority could not be validated for this session.");
+  }
+  return bindToRequest(record, signed, "cli-grant");
+}
 async function activateUnboundCompactImport(node, delegation, host) {
   const activated = await nodeSdk2.activateValidatedRuntimeDelegation(node, delegation, { host });
-  return bindToSignedCapabilities(
+  return bindToRequest(
     // The record keeps the delegation as imported; replay validates it again.
     { delegation, permissions: [...activated.effectivePermissions] },
     activated.effectivePermissions,
@@ -1334,23 +1378,41 @@ async function migratedRecord(node, entry, host, recordedAt) {
   const signed = await signedCapabilities(node, delegation, host);
   if (signed === void 0) return void 0;
   try {
-    return bindToSignedCapabilities({ ...entry, delegation: { ...entry.delegation, cid: delegation.cid } }, signed, "migration", recordedAt);
+    return bindToRequest({ ...entry, delegation: { ...entry.delegation, cid: delegation.cid } }, signed, "migration", recordedAt);
   } catch {
     return void 0;
   }
 }
+var NOT_REPLAYED = { status: "not-replayed" };
+function skipped(reason) {
+  return { status: "skipped", reason };
+}
 async function replayStoredDelegation(node, entry, options) {
+  const kind = storedDelegationKind(entry);
   const delegation = normalizeStoredDelegation(entry);
-  if (delegation === void 0 || delegation.expiry.getTime() <= Date.now()) return void 0;
+  if (kind === "refused" || delegation === void 0) return skipped("malformed");
+  if (delegation.expiry.getTime() <= Date.now()) return NOT_REPLAYED;
+  if (kind === "other") return skipped("proof_missing");
   const limit = replayLimit(entry, options.migrated);
-  if (limit === void 0) return void 0;
-  const authorize = limit === "signed" ? () => true : (effective) => delegationWithinRequest(limit, effective, options.resolveSpace);
+  if (limit === void 0) return skipped("unbound");
+  let outsideRequest = false;
+  const authorize = limit === "signed" ? () => true : (effective) => {
+    outsideRequest = !delegationWithinRequest(limit, effective, options.resolveSpace);
+    return !outsideRequest;
+  };
   try {
-    return await nodeSdk2.activateValidatedRuntimeDelegation(node, delegation, { host: options.host, authorize });
-  } catch {
-    return void 0;
+    return {
+      status: "installed",
+      delegation: await nodeSdk2.activateValidatedRuntimeDelegation(node, delegation, { host: options.host, authorize })
+    };
+  } catch (error) {
+    return skipped(outsideRequest ? "outside_request" : rejectionReason(error));
   }
 }
+function rejectionReason(error) {
+  const reason = isRecord(error) ? error.reason : void 0;
+  return typeof reason === "string" && STORED_GRANT_SKIP_REASONS.includes(reason) ? reason : "invalid";
+}
 async function bindingMigrationRecorded(profile) {
   try {
     return await readJson(bindingMigrationPath(profile)) !== null;
@@ -1399,6 +1461,7 @@ function isRecord(value) {
 0 && (module.exports = {
   BINDING_NOTES,
   activateUnboundCompactImport,
+  bindCliGrant,
   bindingMigrationPath,
   bindingMigrationRecorded,
   mergeDelegationsWithoutRequest,