@tinycloud/operations 0.4.0-beta.9 → 0.4.0

package/dist/delegation-binding.d.cts

@@ -1,5 +1,6 @@
-import { RuntimeDelegationActivator, PortableDelegation, PermissionEntry, ValidatedRuntimeDelegation } from '@tinycloud/node-sdk';
+import { ValidatedRuntimeDelegation, RuntimeDelegationActivator, PortableDelegation, PermissionEntry } from '@tinycloud/node-sdk';
 import { O as OperationSpaceResolver } from './authority-ofwbEqmj.cjs';
+import { S as StoredGrantSkipReason } from './contract-BRwWJpPs.cjs';
 import '@tinycloud/sdk-core';
 
 /** Creates the one owner-aware resolver shared by operation matching paths. */
@@ -19,16 +20,20 @@ declare function operationSpaceResolver(node: unknown, ownerSpace?: string): (sp
  *   own signed capabilities (`unbound-import:<cid>`).
  * - The one-time migration of records stored before bindings existed: exactly
  *   each record's own signed capabilities (`migrated:<cid>`).
+ * - The CLI's own grants (`tc auth request --grant`, permission escalation),
+ *   once checked against the request they answer: exactly each grant's own
+ *   signed capabilities (`cli-grant:<cid>`). Their signed-login records carry
+ *   the `siweProof` replay verifies them from.
  *
- * Records the CLI stores from its own signed-login grants carry no
- * `siweProof`, cannot be verified here, and keep their legacy CLI replay.
+ * Signed-login records the CLI stored before it kept a `siweProof` cannot be
+ * verified here and keep their legacy CLI replay.
  *
  * The binding is local profile data. It stops records written by any other
  * path from granting authority. It does not stop someone who can write the
  * profile directory, who already holds the session key and the signed bytes.
  */
-type BindingSource = "migration" | "unbound-import";
-/** The audit note written beside a binding synthesized from a record's own signed capabilities. */
+type BindingSource = "migration" | "unbound-import" | "cli-grant";
+/** The audit note written beside a binding the record's writer synthesized. */
 declare const BINDING_NOTES: Record<BindingSource, string>;
 /** The per-profile marker: present once that profile's unbound records were migrated. */
 declare function bindingMigrationPath(profile: string): string;
@@ -38,9 +43,9 @@ declare function bindingMigrationPath(profile: string): string;
  * - `compact` and `signed-login` records go through validated activation and
  *   the binding rule.
  * - `other` records keep the CLI's legacy replay: an unbound record whose
- *   bytes are not compact and that has no `siweProof`, which is how the CLI
- *   stores its own signed-login grants. The operations runtime never installs
- *   them.
+ *   bytes are not compact and that has no `siweProof`, which is how earlier
+ *   CLI releases stored their own signed-login grants. The operations runtime
+ *   never installs them.
  * - `refused` records install nothing anywhere.
  *
  * A record is `refused` unless its `delegationHeader` has exactly one own
@@ -61,6 +66,16 @@ declare function storedDelegationKind(entry: unknown): "compact" | "signed-login
  * when the record installs nothing.
  */
 declare function replayLimit(entry: unknown, migrated: boolean): readonly PermissionEntry[] | "signed" | undefined;
+/**
+ * Binds the record of one of the CLI's own grants, already checked against
+ * the request it answers, to exactly the capabilities its signed bytes grant.
+ * They are read through the validated activation replay uses (nothing is
+ * activated), so the binding is the authority replay will derive. Throws when
+ * validated activation cannot read them for `node`'s session.
+ */
+declare function bindCliGrant<T extends {
+    readonly delegation: PortableDelegation;
+}>(node: RuntimeDelegationActivator, record: T, host: string): Promise<T & Record<"authorityRequest" | "authorityRequestAudit", unknown>>;
 /**
  * Validates and activates a compact delegation that `tc auth import` received
  * without a stored request, through the same validated activation replay uses,
@@ -110,21 +125,36 @@ declare function prepareStoredDelegationReplay(profile: string, node: RuntimeDel
     readonly host: string;
     readonly migrate: boolean;
 }): Promise<boolean>;
+/**
+ * What replay did with one stored record. `skipped` records grant nothing and
+ * carry a fixed reason code that is safe to publish; `not-replayed` records
+ * are routine (expired) and give nothing to act on.
+ */
+type StoredDelegationReplay = {
+    readonly status: "installed";
+    readonly delegation: ValidatedRuntimeDelegation;
+} | {
+    readonly status: "skipped";
+    readonly reason: StoredGrantSkipReason;
+} | {
+    readonly status: "not-replayed";
+};
 /**
  * Replays one stored record under the binding rule. A record with a valid
  * binding installs only if its signed capabilities fit inside it. Before the
  * profile has migrated, an unbound compact record installs with its signed
  * authority as it always did; after, it installs nothing. A signed-login
- * record installs only with a binding. Returns the installed delegation, or
- * `undefined` when the record installs nothing. Never throws: stored data is
- * untrusted transport material.
+ * record installs only with a binding. A record with neither compact bytes
+ * nor a `siweProof` cannot be verified here and installs nothing. Never
+ * throws, and never reports exception text: stored data is untrusted
+ * transport material, and messages can quote it or a node's response.
  */
 declare function replayStoredDelegation(node: RuntimeDelegationActivator, entry: unknown, options: {
     readonly host: string;
     readonly migrated: boolean;
     readonly resolveSpace: OperationSpaceResolver;
-}): Promise<ValidatedRuntimeDelegation | undefined>;
+}): Promise<StoredDelegationReplay>;
 /** An unreadable marker counts as migrated: a damaged marker never reopens migration. */
 declare function bindingMigrationRecorded(profile: string): Promise<boolean>;
 
-export { BINDING_NOTES, type BindingSource, activateUnboundCompactImport, bindingMigrationPath, bindingMigrationRecorded, mergeDelegationsWithoutRequest, operationSpaceResolver, prepareStoredDelegationReplay, replayLimit, replayStoredDelegation, storedDelegationKind };
+export { BINDING_NOTES, type BindingSource, type StoredDelegationReplay, activateUnboundCompactImport, bindCliGrant, bindingMigrationPath, bindingMigrationRecorded, mergeDelegationsWithoutRequest, operationSpaceResolver, prepareStoredDelegationReplay, replayLimit, replayStoredDelegation, storedDelegationKind };

package/dist/delegation-binding.d.ts

@@ -1,5 +1,6 @@
-import { RuntimeDelegationActivator, PortableDelegation, PermissionEntry, ValidatedRuntimeDelegation } from '@tinycloud/node-sdk';
+import { ValidatedRuntimeDelegation, RuntimeDelegationActivator, PortableDelegation, PermissionEntry } from '@tinycloud/node-sdk';
 import { O as OperationSpaceResolver } from './authority-ofwbEqmj.js';
+import { S as StoredGrantSkipReason } from './contract-BRwWJpPs.js';
 import '@tinycloud/sdk-core';
 
 /** Creates the one owner-aware resolver shared by operation matching paths. */
@@ -19,16 +20,20 @@ declare function operationSpaceResolver(node: unknown, ownerSpace?: string): (sp
  *   own signed capabilities (`unbound-import:<cid>`).
  * - The one-time migration of records stored before bindings existed: exactly
  *   each record's own signed capabilities (`migrated:<cid>`).
+ * - The CLI's own grants (`tc auth request --grant`, permission escalation),
+ *   once checked against the request they answer: exactly each grant's own
+ *   signed capabilities (`cli-grant:<cid>`). Their signed-login records carry
+ *   the `siweProof` replay verifies them from.
  *
- * Records the CLI stores from its own signed-login grants carry no
- * `siweProof`, cannot be verified here, and keep their legacy CLI replay.
+ * Signed-login records the CLI stored before it kept a `siweProof` cannot be
+ * verified here and keep their legacy CLI replay.
  *
  * The binding is local profile data. It stops records written by any other
  * path from granting authority. It does not stop someone who can write the
  * profile directory, who already holds the session key and the signed bytes.
  */
-type BindingSource = "migration" | "unbound-import";
-/** The audit note written beside a binding synthesized from a record's own signed capabilities. */
+type BindingSource = "migration" | "unbound-import" | "cli-grant";
+/** The audit note written beside a binding the record's writer synthesized. */
 declare const BINDING_NOTES: Record<BindingSource, string>;
 /** The per-profile marker: present once that profile's unbound records were migrated. */
 declare function bindingMigrationPath(profile: string): string;
@@ -38,9 +43,9 @@ declare function bindingMigrationPath(profile: string): string;
  * - `compact` and `signed-login` records go through validated activation and
  *   the binding rule.
  * - `other` records keep the CLI's legacy replay: an unbound record whose
- *   bytes are not compact and that has no `siweProof`, which is how the CLI
- *   stores its own signed-login grants. The operations runtime never installs
- *   them.
+ *   bytes are not compact and that has no `siweProof`, which is how earlier
+ *   CLI releases stored their own signed-login grants. The operations runtime
+ *   never installs them.
  * - `refused` records install nothing anywhere.
  *
  * A record is `refused` unless its `delegationHeader` has exactly one own
@@ -61,6 +66,16 @@ declare function storedDelegationKind(entry: unknown): "compact" | "signed-login
  * when the record installs nothing.
  */
 declare function replayLimit(entry: unknown, migrated: boolean): readonly PermissionEntry[] | "signed" | undefined;
+/**
+ * Binds the record of one of the CLI's own grants, already checked against
+ * the request it answers, to exactly the capabilities its signed bytes grant.
+ * They are read through the validated activation replay uses (nothing is
+ * activated), so the binding is the authority replay will derive. Throws when
+ * validated activation cannot read them for `node`'s session.
+ */
+declare function bindCliGrant<T extends {
+    readonly delegation: PortableDelegation;
+}>(node: RuntimeDelegationActivator, record: T, host: string): Promise<T & Record<"authorityRequest" | "authorityRequestAudit", unknown>>;
 /**
  * Validates and activates a compact delegation that `tc auth import` received
  * without a stored request, through the same validated activation replay uses,
@@ -110,21 +125,36 @@ declare function prepareStoredDelegationReplay(profile: string, node: RuntimeDel
     readonly host: string;
     readonly migrate: boolean;
 }): Promise<boolean>;
+/**
+ * What replay did with one stored record. `skipped` records grant nothing and
+ * carry a fixed reason code that is safe to publish; `not-replayed` records
+ * are routine (expired) and give nothing to act on.
+ */
+type StoredDelegationReplay = {
+    readonly status: "installed";
+    readonly delegation: ValidatedRuntimeDelegation;
+} | {
+    readonly status: "skipped";
+    readonly reason: StoredGrantSkipReason;
+} | {
+    readonly status: "not-replayed";
+};
 /**
  * Replays one stored record under the binding rule. A record with a valid
  * binding installs only if its signed capabilities fit inside it. Before the
  * profile has migrated, an unbound compact record installs with its signed
  * authority as it always did; after, it installs nothing. A signed-login
- * record installs only with a binding. Returns the installed delegation, or
- * `undefined` when the record installs nothing. Never throws: stored data is
- * untrusted transport material.
+ * record installs only with a binding. A record with neither compact bytes
+ * nor a `siweProof` cannot be verified here and installs nothing. Never
+ * throws, and never reports exception text: stored data is untrusted
+ * transport material, and messages can quote it or a node's response.
  */
 declare function replayStoredDelegation(node: RuntimeDelegationActivator, entry: unknown, options: {
     readonly host: string;
     readonly migrated: boolean;
     readonly resolveSpace: OperationSpaceResolver;
-}): Promise<ValidatedRuntimeDelegation | undefined>;
+}): Promise<StoredDelegationReplay>;
 /** An unreadable marker counts as migrated: a damaged marker never reopens migration. */
 declare function bindingMigrationRecorded(profile: string): Promise<boolean>;
 
-export { BINDING_NOTES, type BindingSource, activateUnboundCompactImport, bindingMigrationPath, bindingMigrationRecorded, mergeDelegationsWithoutRequest, operationSpaceResolver, prepareStoredDelegationReplay, replayLimit, replayStoredDelegation, storedDelegationKind };
+export { BINDING_NOTES, type BindingSource, type StoredDelegationReplay, activateUnboundCompactImport, bindCliGrant, bindingMigrationPath, bindingMigrationRecorded, mergeDelegationsWithoutRequest, operationSpaceResolver, prepareStoredDelegationReplay, replayLimit, replayStoredDelegation, storedDelegationKind };

package/dist/delegation-binding.js

@@ -257,8 +257,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}/`);
@@ -573,7 +582,8 @@ async function acquireProfileLock(profile, options) {
   const lockPath = profileLockPath(profile);
   const turnDirectory = profileTurnLockPath(profile);
   const directory = profilePath(profile);
-  await mkdir(directory, { recursive: true, mode: PRIVATE_DIR_MODE });
+  if (options.requireProfile && !await exists(profileConfigPath(profile))) throw new ProfileDeletedError(profile);
+  if (!options.requireProfile) await mkdir(directory, { recursive: true, mode: PRIVATE_DIR_MODE });
   await mkdir(dirname(turnDirectory), { recursive: true, mode: PRIVATE_DIR_MODE });
   for (const path of [tinycloudHomePath(), profilesPath(), directory]) {
     await chmod(path, PRIVATE_DIR_MODE).catch((error) => {
@@ -582,11 +592,15 @@ async function acquireProfileLock(profile, options) {
   }
   const { turn, firstWaitedTurn } = await acquireTurn(profile, turnDirectory, deadline);
   try {
+    if (options.requireProfile && !await exists(profileConfigPath(profile))) {
+      await rmdir(directory).catch(() => void 0);
+      throw new ProfileDeletedError(profile);
+    }
     const deletion = await readJson(join(turnDirectory, "deleted.json")).catch(() => null);
     const deletedWhileWaiting = typeof deletion?.slot === "number" && deletion.slot >= firstWaitedTurn;
     while (true) {
       const token = randomUUID();
-      if (await publishProfileLock(profile, lockPath, token)) {
+      if (await publishProfileLock(profile, lockPath, token, options.requireProfile === true)) {
         return {
           deletedWhileWaiting,
           turnSlot: turn.slot,
@@ -837,12 +851,13 @@ async function collectTurns(profile, turn) {
     }
   }
 }
-async function publishProfileLock(profile, lockPath, token) {
+async function publishProfileLock(profile, lockPath, token, requireProfile) {
   try {
     await 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 mkdir(profilePath(profile), { recursive: true, mode: PRIVATE_DIR_MODE });
     return false;
   }
@@ -1137,6 +1152,25 @@ var DelegationImportArtifactSchema = 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
 import * as nodeSdk from "@tinycloud/node-sdk";
 
@@ -1217,11 +1251,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) {
@@ -1246,19 +1282,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,
@@ -1327,23 +1370,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;
@@ -1391,6 +1452,7 @@ function isRecord(value) {
 export {
   BINDING_NOTES,
   activateUnboundCompactImport,
+  bindCliGrant,
   bindingMigrationPath,
   bindingMigrationRecorded,
   mergeDelegationsWithoutRequest,