@tinycloud/operations 0.4.0-beta.11 → 0.4.0-beta.13

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

@@ -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-eWtDSMeI.d.ts → contract-BRwWJpPs.d.ts}

@@ -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}/`);
@@ -1144,6 +1154,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 +1253,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 +1284,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 +1372,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 +1455,7 @@ function isRecord(value) {
 0 && (module.exports = {
   BINDING_NOTES,
   activateUnboundCompactImport,
+  bindCliGrant,
   bindingMigrationPath,
   bindingMigrationRecorded,
   mergeDelegationsWithoutRequest,