@tinycloud/operations 0.4.0-beta.8 → 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 };