@tinycloud/operations 0.3.4-beta.6 → 0.4.0-beta.8

package/dist/delegation-binding.d.cts

@@ -0,0 +1,130 @@
+import { RuntimeDelegationActivator, PortableDelegation, PermissionEntry, ValidatedRuntimeDelegation } from '@tinycloud/node-sdk';
+import { O as OperationSpaceResolver } from './authority-ofwbEqmj.cjs';
+import '@tinycloud/sdk-core';
+
+/** Creates the one owner-aware resolver shared by operation matching paths. */
+declare function operationSpaceResolver(node: unknown, ownerSpace?: string): (space: string) => string;
+
+/**
+ * Request bindings for delegations stored in `additional-delegations.json`.
+ *
+ * A compact-UCAN or signed-login (SIWE) record replays only when its
+ * `authorityRequest` binding is valid and the capabilities its signed bytes
+ * grant fit inside the binding's `requested`. Validated activation checks that
+ * before anything is activated. Three writers produce bindings:
+ *
+ * - `tinycloud.auth.import`: the stored request the delegation was checked
+ *   against (`requestId` is that request's).
+ * - `tc auth import` of an artifact with no request: exactly the delegation's
+ *   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>`).
+ *
+ * Records the CLI stores from its own signed-login grants carry no
+ * `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. */
+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 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.
+ */
+declare function storedDelegationKind(entry: unknown): "compact" | "signed-login" | "other" | "refused";
+/**
+ * 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.
+ */
+declare function replayLimit(entry: unknown, migrated: boolean): readonly PermissionEntry[] | "signed" | undefined;
+/**
+ * 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.
+ */
+declare function activateUnboundCompactImport(node: RuntimeDelegationActivator, delegation: PortableDelegation, host: string): Promise<{
+    delegation: PortableDelegation;
+    permissions: PermissionEntry[];
+} & Record<string, unknown>>;
+/**
+ * The stored records after adding records written without a stored request
+ * (by `tc auth import` or a CLI grant). A stored record for the same CID that
+ * carries an `authorityRequest` is kept as it is, so this route never drops,
+ * replaces or weakens a binding; otherwise each record replaces every row for
+ * its CID, at the first one's position, or is appended. Callers write the
+ * result under the profile lock they already use for this store.
+ */
+declare function mergeDelegationsWithoutRequest(stored: readonly unknown[], incoming: readonly ({
+    readonly delegation: {
+        readonly cid: string;
+    };
+} & 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.
+ *
+ * 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`
+ * 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.
+ */
+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.
+ */
+declare function replayStoredDelegation(node: RuntimeDelegationActivator, entry: unknown, options: {
+    readonly host: string;
+    readonly migrated: boolean;
+    readonly resolveSpace: OperationSpaceResolver;
+}): Promise<ValidatedRuntimeDelegation | undefined>;
+/** 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 };

package/dist/delegation-binding.d.ts

@@ -0,0 +1,130 @@
+import { RuntimeDelegationActivator, PortableDelegation, PermissionEntry, ValidatedRuntimeDelegation } from '@tinycloud/node-sdk';
+import { O as OperationSpaceResolver } from './authority-ofwbEqmj.js';
+import '@tinycloud/sdk-core';
+
+/** Creates the one owner-aware resolver shared by operation matching paths. */
+declare function operationSpaceResolver(node: unknown, ownerSpace?: string): (space: string) => string;
+
+/**
+ * Request bindings for delegations stored in `additional-delegations.json`.
+ *
+ * A compact-UCAN or signed-login (SIWE) record replays only when its
+ * `authorityRequest` binding is valid and the capabilities its signed bytes
+ * grant fit inside the binding's `requested`. Validated activation checks that
+ * before anything is activated. Three writers produce bindings:
+ *
+ * - `tinycloud.auth.import`: the stored request the delegation was checked
+ *   against (`requestId` is that request's).
+ * - `tc auth import` of an artifact with no request: exactly the delegation's
+ *   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>`).
+ *
+ * Records the CLI stores from its own signed-login grants carry no
+ * `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. */
+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 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.
+ */
+declare function storedDelegationKind(entry: unknown): "compact" | "signed-login" | "other" | "refused";
+/**
+ * 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.
+ */
+declare function replayLimit(entry: unknown, migrated: boolean): readonly PermissionEntry[] | "signed" | undefined;
+/**
+ * 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.
+ */
+declare function activateUnboundCompactImport(node: RuntimeDelegationActivator, delegation: PortableDelegation, host: string): Promise<{
+    delegation: PortableDelegation;
+    permissions: PermissionEntry[];
+} & Record<string, unknown>>;
+/**
+ * The stored records after adding records written without a stored request
+ * (by `tc auth import` or a CLI grant). A stored record for the same CID that
+ * carries an `authorityRequest` is kept as it is, so this route never drops,
+ * replaces or weakens a binding; otherwise each record replaces every row for
+ * its CID, at the first one's position, or is appended. Callers write the
+ * result under the profile lock they already use for this store.
+ */
+declare function mergeDelegationsWithoutRequest(stored: readonly unknown[], incoming: readonly ({
+    readonly delegation: {
+        readonly cid: string;
+    };
+} & 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.
+ *
+ * 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`
+ * 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.
+ */
+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.
+ */
+declare function replayStoredDelegation(node: RuntimeDelegationActivator, entry: unknown, options: {
+    readonly host: string;
+    readonly migrated: boolean;
+    readonly resolveSpace: OperationSpaceResolver;
+}): Promise<ValidatedRuntimeDelegation | undefined>;
+/** 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 };