@tinycloud/operations 0.4.0-beta.9 → 0.5.0-beta.0

package/dist/delegation-binding.d.cts

@@ -1,5 +1,7 @@
-import { RuntimeDelegationActivator, PortableDelegation, PermissionEntry, ValidatedRuntimeDelegation } from '@tinycloud/node-sdk';
+import { PermissionEntry, ValidatedRuntimeDelegation, RuntimeDelegationActivator, PortableDelegation } from '@tinycloud/node-sdk';
 import { O as OperationSpaceResolver } from './authority-ofwbEqmj.cjs';
+import { S as StoredGrantSkipReason, b as OperationWarning } from './contract-DfyrluLB.cjs';
+export { c as STORED_GRANT_SKIP_REASONS } from './contract-DfyrluLB.cjs';
 import '@tinycloud/sdk-core';
 
 /** Creates the one owner-aware resolver shared by operation matching paths. */
@@ -19,55 +21,54 @@ 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 without a `siweProof` cannot be
+ * verified from signed bytes and are not installed by either runtime.
  *
  * 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;
 /**
- * How replay treats a stored record:
+ * Compact and signed-login records require a valid request binding and signed
+ * proof. A legacy record with no proof is classified `other` only so replay
+ * can report `proof_missing`; it never installs. Malformed headers are refused.
  *
- * - `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.
- * - `refused` records install nothing anywhere.
- *
- * A record is `refused` unless its `delegationHeader` has exactly one own
- * key, `Authorization`, with a string value: header names are matched
- * case-insensitively on the wire, and other value types are stringified, so
- * any other shape could reach the node as authorization bytes this rule never
- * read. Bytes containing a `.` are never `other`: a CACAO has none, and
- * validated activation refuses anything compact-shaped that it cannot parse.
- * A record with an `authorityRequest` (valid or not) is never `other`: the
- * legacy path cannot hold it to a binding, so dropping a `siweProof` cannot
- * route a bound signed-login delegation around its binding.
+ * A header must contain exactly one `Authorization` string key: other shapes
+ * might reach the node as authorization bytes this rule never examined.
  */
 declare function storedDelegationKind(entry: unknown): "compact" | "signed-login" | "other" | "refused";
+/** A record replays only within a valid stored request binding. */
+declare function replayLimit(entry: unknown): readonly PermissionEntry[] | undefined;
+/** Match node-sdk's normalization before validating a compact signature. */
+declare function withoutBearer(authorization: string): string;
+type StoredDelegationSource = "cli-grant" | "unbound-import" | "migration" | "request" | "legacy" | "unknown";
+/** Constrained labels only; never publish untrusted request IDs or audit notes. */
+declare function storedDelegationSource(entry: unknown): StoredDelegationSource;
 /**
- * What replay holds a stored record to: its binding's `requested`, `"signed"`
- * for an unbound compact record before the profile has migrated (it installs
- * with its own signed authority, as before bindings existed), or `undefined`
- * when the record installs nothing.
+ * 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 replayLimit(entry: unknown, migrated: boolean): readonly PermissionEntry[] | "signed" | undefined;
+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,
- * and returns its record bound to exactly the capabilities its signed bytes
- * grant. Throws when validation or activation fails.
+ * Validates and activates an imported compact or signed-login delegation,
+ * binding its record to exactly its verified signed capabilities.
  */
-declare function activateUnboundCompactImport(node: RuntimeDelegationActivator, delegation: PortableDelegation, host: string): Promise<{
+declare function activateUnboundImport(node: RuntimeDelegationActivator, delegation: PortableDelegation, host: string): Promise<{
     delegation: PortableDelegation;
     permissions: PermissionEntry[];
 } & Record<string, unknown>>;
@@ -85,46 +86,89 @@ declare function mergeDelegationsWithoutRequest(stored: readonly unknown[], inco
     };
 } & Record<string, unknown>)[]): unknown[];
 /**
- * Runs before replay reads the profile's records, so those records and the
- * migration marker agree. Returns whether the profile has migrated.
+ * Runs migration before replay reads the profile's records. Returns whether
+ * the marker exists; replay refuses unbound records either way.
  *
- * Migration runs under the profile lock, and only while the profile's
- * persisted session is still the one `node` restored: a session rotated since
- * the restore leaves migration to a runtime of the new session. Each compact
- * record with no `authorityRequest` is handled on its own: if validated
- * activation can read its signed capabilities (CID, expiry, audience and
- * declared resources checked, nothing activated) and they form a valid
- * binding, the record is bound to exactly those capabilities; otherwise it
- * stays unbound, is listed in the marker's `unbound`, and installs nothing
- * after migration. A compact record whose capabilities cannot be read could
- * not activate for this session either. `migrate` must be false unless `node`
+ * Migration runs under the profile lock, and only while the persisted session
+ * is still the one `node` restored. Each unbound compact record is checked
+ * without activation and bound to exactly its signed capabilities, or left
+ * unbound when validation fails. `migrate` must be false unless the node
  * holds the profile's own restored session.
  *
- * Migration is best-effort and restartable. The bound records are written
- * first and the marker last; a busy lock or any failure before the marker
- * leaves the profile unmigrated, so this runtime replays under the
- * pre-migration rule and the next one migrates again. Records already bound
- * by an interrupted run keep their bindings.
+ * Migration is best-effort and restartable. Bound records are written before
+ * the marker; a busy lock or failure leaves migration for a later runtime.
+ * Records already bound by an interrupted run keep their bindings.
  */
 declare function prepareStoredDelegationReplay(profile: string, node: RuntimeDelegationActivator, options: {
     readonly host: string;
     readonly migrate: boolean;
 }): Promise<boolean>;
 /**
- * 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.
+ * 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";
+};
+/**
+ * The single stored-grant replay path for CLI and canonical runtimes.
+ * Migration runs before the store read; CID deduplication affects authority
+ * only, not the per-record fixed-code skip diagnostics.
+ */
+declare function replayProfileDelegations(profile: string, node: RuntimeDelegationActivator, options: {
+    readonly host: string;
+    readonly migrate: boolean;
+    readonly resolveSpace: OperationSpaceResolver;
+}): Promise<{
+    installed: ValidatedRuntimeDelegation[];
+    warnings: OperationWarning[];
+}>;
+/** Return an audience only after the exact compact bytes, CID and signature verify. */
+declare function verifiedCompactAudience(node: RuntimeDelegationActivator, delegation: PortableDelegation): string | undefined;
+/** Only a verified signed audience and matching transport audience can identify a foreign grant. */
+declare function storedDelegationForAnotherKey(entry: unknown, node: RuntimeDelegationActivator): boolean;
+/**
+ * Publish a stored CID only when it matches the stored authorization bytes.
+ * Free-text and even correctly shaped CIDs of different bytes stay private.
+ */
+declare function verifiedStoredCid(node: RuntimeDelegationActivator, entry: unknown): string | undefined;
+/**
+ * Replays one stored record under its binding, never installing an unbound or
+ * unproven grant. Stored bytes and node messages are never published.
  */
 declare function replayStoredDelegation(node: RuntimeDelegationActivator, entry: unknown, options: {
     readonly host: string;
-    readonly migrated: boolean;
     readonly resolveSpace: OperationSpaceResolver;
-}): Promise<ValidatedRuntimeDelegation | undefined>;
+}): Promise<StoredDelegationReplay>;
+type StoredDelegationInspection = {
+    readonly local: "verified";
+    readonly cid: string;
+    readonly effectivePermissions: readonly PermissionEntry[];
+    readonly expiry: Date;
+} | {
+    readonly local: "refused";
+    readonly reason: StoredGrantSkipReason;
+} | {
+    readonly local: "not_checked";
+    readonly because: "expired" | "no_session";
+};
+/**
+ * Checks only local signed bytes, expiry, audience, resources and binding.
+ * The node still decides delegation-chain validity and revocation at install.
+ */
+declare function inspectStoredDelegation(entry: unknown, options?: {
+    readonly node?: RuntimeDelegationActivator;
+    readonly host?: string;
+    readonly resolveSpace?: OperationSpaceResolver;
+}): Promise<StoredDelegationInspection>;
 /** 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, OperationWarning, type StoredDelegationInspection, type StoredDelegationReplay, type StoredDelegationSource, StoredGrantSkipReason, activateUnboundImport, bindCliGrant, bindingMigrationPath, bindingMigrationRecorded, inspectStoredDelegation, mergeDelegationsWithoutRequest, operationSpaceResolver, prepareStoredDelegationReplay, replayLimit, replayProfileDelegations, replayStoredDelegation, storedDelegationForAnotherKey, storedDelegationKind, storedDelegationSource, verifiedCompactAudience, verifiedStoredCid, withoutBearer };

package/dist/delegation-binding.d.ts

@@ -1,5 +1,7 @@
-import { RuntimeDelegationActivator, PortableDelegation, PermissionEntry, ValidatedRuntimeDelegation } from '@tinycloud/node-sdk';
+import { PermissionEntry, ValidatedRuntimeDelegation, RuntimeDelegationActivator, PortableDelegation } from '@tinycloud/node-sdk';
 import { O as OperationSpaceResolver } from './authority-ofwbEqmj.js';
+import { S as StoredGrantSkipReason, b as OperationWarning } from './contract-DfyrluLB.js';
+export { c as STORED_GRANT_SKIP_REASONS } from './contract-DfyrluLB.js';
 import '@tinycloud/sdk-core';
 
 /** Creates the one owner-aware resolver shared by operation matching paths. */
@@ -19,55 +21,54 @@ 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 without a `siweProof` cannot be
+ * verified from signed bytes and are not installed by either runtime.
  *
  * 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;
 /**
- * How replay treats a stored record:
+ * Compact and signed-login records require a valid request binding and signed
+ * proof. A legacy record with no proof is classified `other` only so replay
+ * can report `proof_missing`; it never installs. Malformed headers are refused.
  *
- * - `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.
- * - `refused` records install nothing anywhere.
- *
- * A record is `refused` unless its `delegationHeader` has exactly one own
- * key, `Authorization`, with a string value: header names are matched
- * case-insensitively on the wire, and other value types are stringified, so
- * any other shape could reach the node as authorization bytes this rule never
- * read. Bytes containing a `.` are never `other`: a CACAO has none, and
- * validated activation refuses anything compact-shaped that it cannot parse.
- * A record with an `authorityRequest` (valid or not) is never `other`: the
- * legacy path cannot hold it to a binding, so dropping a `siweProof` cannot
- * route a bound signed-login delegation around its binding.
+ * A header must contain exactly one `Authorization` string key: other shapes
+ * might reach the node as authorization bytes this rule never examined.
  */
 declare function storedDelegationKind(entry: unknown): "compact" | "signed-login" | "other" | "refused";
+/** A record replays only within a valid stored request binding. */
+declare function replayLimit(entry: unknown): readonly PermissionEntry[] | undefined;
+/** Match node-sdk's normalization before validating a compact signature. */
+declare function withoutBearer(authorization: string): string;
+type StoredDelegationSource = "cli-grant" | "unbound-import" | "migration" | "request" | "legacy" | "unknown";
+/** Constrained labels only; never publish untrusted request IDs or audit notes. */
+declare function storedDelegationSource(entry: unknown): StoredDelegationSource;
 /**
- * What replay holds a stored record to: its binding's `requested`, `"signed"`
- * for an unbound compact record before the profile has migrated (it installs
- * with its own signed authority, as before bindings existed), or `undefined`
- * when the record installs nothing.
+ * 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 replayLimit(entry: unknown, migrated: boolean): readonly PermissionEntry[] | "signed" | undefined;
+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,
- * and returns its record bound to exactly the capabilities its signed bytes
- * grant. Throws when validation or activation fails.
+ * Validates and activates an imported compact or signed-login delegation,
+ * binding its record to exactly its verified signed capabilities.
  */
-declare function activateUnboundCompactImport(node: RuntimeDelegationActivator, delegation: PortableDelegation, host: string): Promise<{
+declare function activateUnboundImport(node: RuntimeDelegationActivator, delegation: PortableDelegation, host: string): Promise<{
     delegation: PortableDelegation;
     permissions: PermissionEntry[];
 } & Record<string, unknown>>;
@@ -85,46 +86,89 @@ declare function mergeDelegationsWithoutRequest(stored: readonly unknown[], inco
     };
 } & Record<string, unknown>)[]): unknown[];
 /**
- * Runs before replay reads the profile's records, so those records and the
- * migration marker agree. Returns whether the profile has migrated.
+ * Runs migration before replay reads the profile's records. Returns whether
+ * the marker exists; replay refuses unbound records either way.
  *
- * Migration runs under the profile lock, and only while the profile's
- * persisted session is still the one `node` restored: a session rotated since
- * the restore leaves migration to a runtime of the new session. Each compact
- * record with no `authorityRequest` is handled on its own: if validated
- * activation can read its signed capabilities (CID, expiry, audience and
- * declared resources checked, nothing activated) and they form a valid
- * binding, the record is bound to exactly those capabilities; otherwise it
- * stays unbound, is listed in the marker's `unbound`, and installs nothing
- * after migration. A compact record whose capabilities cannot be read could
- * not activate for this session either. `migrate` must be false unless `node`
+ * Migration runs under the profile lock, and only while the persisted session
+ * is still the one `node` restored. Each unbound compact record is checked
+ * without activation and bound to exactly its signed capabilities, or left
+ * unbound when validation fails. `migrate` must be false unless the node
  * holds the profile's own restored session.
  *
- * Migration is best-effort and restartable. The bound records are written
- * first and the marker last; a busy lock or any failure before the marker
- * leaves the profile unmigrated, so this runtime replays under the
- * pre-migration rule and the next one migrates again. Records already bound
- * by an interrupted run keep their bindings.
+ * Migration is best-effort and restartable. Bound records are written before
+ * the marker; a busy lock or failure leaves migration for a later runtime.
+ * Records already bound by an interrupted run keep their bindings.
  */
 declare function prepareStoredDelegationReplay(profile: string, node: RuntimeDelegationActivator, options: {
     readonly host: string;
     readonly migrate: boolean;
 }): Promise<boolean>;
 /**
- * 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.
+ * 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";
+};
+/**
+ * The single stored-grant replay path for CLI and canonical runtimes.
+ * Migration runs before the store read; CID deduplication affects authority
+ * only, not the per-record fixed-code skip diagnostics.
+ */
+declare function replayProfileDelegations(profile: string, node: RuntimeDelegationActivator, options: {
+    readonly host: string;
+    readonly migrate: boolean;
+    readonly resolveSpace: OperationSpaceResolver;
+}): Promise<{
+    installed: ValidatedRuntimeDelegation[];
+    warnings: OperationWarning[];
+}>;
+/** Return an audience only after the exact compact bytes, CID and signature verify. */
+declare function verifiedCompactAudience(node: RuntimeDelegationActivator, delegation: PortableDelegation): string | undefined;
+/** Only a verified signed audience and matching transport audience can identify a foreign grant. */
+declare function storedDelegationForAnotherKey(entry: unknown, node: RuntimeDelegationActivator): boolean;
+/**
+ * Publish a stored CID only when it matches the stored authorization bytes.
+ * Free-text and even correctly shaped CIDs of different bytes stay private.
+ */
+declare function verifiedStoredCid(node: RuntimeDelegationActivator, entry: unknown): string | undefined;
+/**
+ * Replays one stored record under its binding, never installing an unbound or
+ * unproven grant. Stored bytes and node messages are never published.
  */
 declare function replayStoredDelegation(node: RuntimeDelegationActivator, entry: unknown, options: {
     readonly host: string;
-    readonly migrated: boolean;
     readonly resolveSpace: OperationSpaceResolver;
-}): Promise<ValidatedRuntimeDelegation | undefined>;
+}): Promise<StoredDelegationReplay>;
+type StoredDelegationInspection = {
+    readonly local: "verified";
+    readonly cid: string;
+    readonly effectivePermissions: readonly PermissionEntry[];
+    readonly expiry: Date;
+} | {
+    readonly local: "refused";
+    readonly reason: StoredGrantSkipReason;
+} | {
+    readonly local: "not_checked";
+    readonly because: "expired" | "no_session";
+};
+/**
+ * Checks only local signed bytes, expiry, audience, resources and binding.
+ * The node still decides delegation-chain validity and revocation at install.
+ */
+declare function inspectStoredDelegation(entry: unknown, options?: {
+    readonly node?: RuntimeDelegationActivator;
+    readonly host?: string;
+    readonly resolveSpace?: OperationSpaceResolver;
+}): Promise<StoredDelegationInspection>;
 /** 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, OperationWarning, type StoredDelegationInspection, type StoredDelegationReplay, type StoredDelegationSource, StoredGrantSkipReason, activateUnboundImport, bindCliGrant, bindingMigrationPath, bindingMigrationRecorded, inspectStoredDelegation, mergeDelegationsWithoutRequest, operationSpaceResolver, prepareStoredDelegationReplay, replayLimit, replayProfileDelegations, replayStoredDelegation, storedDelegationForAnotherKey, storedDelegationKind, storedDelegationSource, verifiedCompactAudience, verifiedStoredCid, withoutBearer };