@tinycloud/sdk-services 3.7.0-beta.3 → 3.7.0

package/dist/encryption/named-keys.d.ts

@@ -0,0 +1,220 @@
+import { E as EncryptionCrypto, I as InlineEncryptedEnvelope, J as Json } from '../types-BGRzS1ob.js';
+import { ParsedKeyResource } from './resource.js';
+import '../types-DAOyIbXu.js';
+
+/**
+ * Named-key client: key admin, descriptor reads, `ensureKey` and key-scoped
+ * encrypt / decrypt.
+ *
+ * Rules enforced here:
+ * - Everything is dark unless the node's `/info` `features` contains
+ *   `encryption-named-keys-v1`. Without it no key ability, key URN or `keyPath`
+ *   is sent to the node; the call throws `NAMED_KEYS_UNSUPPORTED` first.
+ * - Every invocation carries exactly ONE capability whose `with` is the EXACT
+ *   key URN (a parsed `kind: "key"`; a prefix or bare network is never a
+ *   target) and whose `can` is the one ability the call needs.
+ * - Admin bodies are hashed and serialized with the same canonical JSON used
+ *   by the network-admin invocation (`canonicalHashHex` / `canonicalize`).
+ * - Envelope v2 carries `keyPath` and is wrapped to the KEY's public key. It is
+ *   decrypted only through `POST /invoke` with a single decrypt capability on
+ *   that key. v1 envelopes (no `keyPath`) go to the root-key path unchanged.
+ *   A key and the root, or two keys, are never mixed in one invocation.
+ * - `key.delete` is not offered. The create body carries `deletable`, which is
+ *   `true` exactly when the path starts with `apps/`; the node refuses it with
+ *   `deletable_unavailable` while app-key deletion is not enabled there.
+ */
+
+declare const KEY_ADMIN_FACT_TYPE: "tinycloud.encryption.key-admin/v1";
+declare const KEY_DESCRIBE_FACT_TYPE: "tinycloud.encryption.key-describe/v1";
+declare const NAMED_KEY_ENVELOPE_VERSION: 2;
+type NamedKeyErrorCode = "NAMED_KEYS_UNSUPPORTED" | "INVALID_KEY_TARGET" | "INVALID_ENVELOPE" | "INVALID_RESPONSE" | "KEY_BLOCKED" | "KEY_NOT_FOUND" | "KEY_EXISTS" | "NETWORK_NOT_FOUND" | "NETWORK_NOT_ACTIVE" | "KEY_LIMIT_EXCEEDED" | "DELETABLE_UNAVAILABLE"
+/** The key is not deletable (a deterministic key answers 409 `key_not_deletable`). */
+ | "KEY_NOT_DELETABLE" | "KEY_PATH_INVALID" | "KEY_UNWRAP_FAILED"
+/** Key is in a state other than active/blocked; `rawState` holds the node's string. */
+ | "KEY_UNAVAILABLE"
+/** `ensureKey` found a key that is not deterministic. */
+ | "KEY_KIND_MISMATCH" | "DECRYPT_FAILED" | "NODE_ERROR"
+/** The node rejected `receiverPublicKey` (400, invocation not consumed). */
+ | "RECEIVER_KEY_INVALID"
+/** The node object lacks an invocation hook the node-sdk wiring needs. */
+ | "NODE_HOOK_MISSING";
+/**
+ * Render an untrusted value (resource, path, node-supplied state, parser or
+ * signer text) for an error message: capped at 120 characters, then every
+ * character outside printable ASCII escaped, so bidi, zero-width and other
+ * format or control characters can never reach a terminal or log through a
+ * message. Raw values live only in non-message fields (`input`, `rawState`,
+ * `kind`, `detail`, `cause`).
+ */
+declare function safeEcho(value: unknown): string;
+interface NamedKeyErrorInit {
+    status?: number;
+    /** The node's `<code>` prefix, when it sent one. */
+    nodeCode?: string;
+    /** The node's `<detail>` text. Raw: never in `message`. */
+    detail?: string;
+    /** Raw state string (KEY_UNAVAILABLE). Raw: never in `message`. */
+    rawState?: string;
+    kind?: string;
+    /** The rejected caller input (resource or path), unescaped. Raw: never in `message`. */
+    input?: string;
+    cause?: unknown;
+}
+declare class NamedKeyError extends Error {
+    readonly code: NamedKeyErrorCode;
+    readonly status?: number;
+    readonly nodeCode?: string;
+    readonly detail?: string;
+    readonly rawState?: string;
+    readonly kind?: string;
+    readonly input?: string;
+    constructor(code: NamedKeyErrorCode, message: string, init?: NamedKeyErrorInit);
+}
+/** Map a node plain-text `<code>: <detail>` error response to a typed error. */
+declare function mapNodeKeyError(status: number, text: string, context: string): NamedKeyError;
+interface PublicKeyDescriptor {
+    networkId: string;
+    keyPath: string;
+    alg: string;
+    keyVersion: number;
+    publicEncryptionKey: string;
+}
+interface KeyDescriptor extends PublicKeyDescriptor {
+    /** Raw node state string (`active`, `blocked`, ...). */
+    state: string;
+    /** `deterministic` outside `apps/`, `deletable` under it; kept as a string so unknown kinds surface. */
+    kind: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** v2 inline envelope: v1 fields plus `keyPath`, wrapped to the key's public key. */
+interface NamedKeyEnvelope extends Omit<InlineEncryptedEnvelope, "v"> {
+    v: typeof NAMED_KEY_ENVELOPE_VERSION;
+    keyPath: string;
+}
+interface NamedKeyInvocationInput {
+    targetNode: string;
+    /** The EXACT key URN. This is the single capability's `with`. */
+    resource: string;
+    /** The single capability's `can`. */
+    action: string;
+    facts: Record<string, unknown>;
+}
+interface NamedKeyClientConfig {
+    host: string;
+    crypto: EncryptionCrypto;
+    fetch: typeof fetch;
+    /** Network used when a call does not name one. */
+    defaultNetworkId: () => string;
+    /** Mint one single-capability invocation and return the Authorization header value. */
+    signInvocation: (input: NamedKeyInvocationInput) => Promise<{
+        authorization: string;
+        invocationCid: string;
+    }>;
+    /**
+     * Decrypt a v1 (root key, bare network capability) envelope exactly as the
+     * existing network decrypt path does.
+     */
+    decryptRoot?: (envelope: InlineEncryptedEnvelope) => Promise<{
+        ok: true;
+        data: Uint8Array;
+    } | {
+        ok: false;
+        error: {
+            message: string;
+        };
+    }>;
+}
+interface KeyCallOptions {
+    /** Full network id URN. Defaults to the client's default network. */
+    networkId?: string;
+}
+interface KeyEncryptOptions extends KeyCallOptions {
+    aad?: Uint8Array;
+    metadata?: Record<string, string>;
+}
+type DecryptManyResult = {
+    ok: true;
+    data: Uint8Array;
+} | {
+    ok: false;
+    error: NamedKeyError;
+};
+/** Accept only a parsed `kind: "key"`; a prefix or bare network is never a target. */
+declare function requireKeyTarget(resource: string): ParsedKeyResource;
+/** `{type, targetNode, networkId, keyPath, action, bodyHash}` for key admin routes. */
+declare function buildKeyAdminFacts(input: {
+    crypto: EncryptionCrypto;
+    targetNode: string;
+    keyResource: string;
+    action: string;
+    body: Json;
+}): Record<string, unknown>;
+/** `{type, targetNode, networkId, keyPath}`; no body hash. */
+declare function buildKeyDescribeFacts(input: {
+    targetNode: string;
+    keyResource: string;
+}): Record<string, unknown>;
+declare class NamedKeyClient {
+    private readonly config;
+    /** One `/info` read per client: the node DID once the feature is confirmed. */
+    private nodeId?;
+    constructor(config: NamedKeyClientConfig);
+    private networkFor;
+    private keyUrn;
+    /**
+     * Require the named-keys feature and return the node DID. The first call
+     * reads `/info`; a positive answer is cached for the life of this client, so
+     * later calls make no `/info` request. A node without the feature is NOT
+     * cached: the typed `NAMED_KEYS_UNSUPPORTED` error is thrown and the next
+     * call re-reads (so a retry sees an upgraded node). No key request is made
+     * before the gate passes.
+     */
+    private requireNode;
+    /** Clear the cached `/info` answer; the next call reads it again. */
+    refreshNodeInfo(): void;
+    private readNodeInfo;
+    private keysUrl;
+    /** Public GET: the key's public key. Derive-only (no 404) outside `apps/`; under `apps/` the node answers 404. */
+    getPublicKey(path: string, options?: KeyCallOptions): Promise<PublicKeyDescriptor>;
+    /**
+     * Authenticated GET: the full descriptor, or `null` on `key_not_found`.
+     * `ability` is the one capability the invocation carries (default decrypt).
+     */
+    describeKey(path: string, options?: KeyCallOptions & {
+        ability?: string;
+    }): Promise<KeyDescriptor | null>;
+    /** Public fields of an authenticated describe (decrypt ability); `key_not_found` throws. */
+    private describePublic;
+    /** The authenticated GET response body, or `null` on `key_not_found`. */
+    private describeBody;
+    private admin;
+    /** `key.create`: `deletable` is `true` exactly under `apps/`, else a deterministic key. */
+    createKey(path: string, options?: KeyCallOptions): Promise<KeyDescriptor>;
+    blockKey(path: string, options?: KeyCallOptions): Promise<KeyDescriptor>;
+    unblockKey(path: string, options?: KeyCallOptions): Promise<KeyDescriptor>;
+    /**
+     * Make sure a key exists and is usable: authenticated GET; on
+     * `key_not_found` create it; on 409 `key_exists` read it again. Succeeds only
+     * for `state: "active"` and the kind the path implies: `deletable` under
+     * `apps/`, `deterministic` elsewhere.
+     */
+    ensureKey(path: string, options?: KeyCallOptions): Promise<KeyDescriptor>;
+    /** Encrypt to a named key: envelope v2, symmetric key wrapped to the key's public key. */
+    encrypt(path: string, plaintext: Uint8Array, options?: KeyEncryptOptions): Promise<NamedKeyEnvelope>;
+    /**
+     * Decrypt one envelope. v1 (no `keyPath`) uses the root-key path exactly as
+     * before; v2 uses one decrypt capability on the exact key via `/invoke`.
+     */
+    decrypt(envelope: InlineEncryptedEnvelope | NamedKeyEnvelope): Promise<Uint8Array>;
+    /**
+     * Decrypt a batch. Each envelope is its own invocation with its own single
+     * capability, so v1 and v2 (or two different keys) are never combined.
+     */
+    decryptMany(envelopes: ReadonlyArray<InlineEncryptedEnvelope | NamedKeyEnvelope>): Promise<DecryptManyResult[]>;
+    private decryptRoot;
+    private validateKeyEnvelope;
+    private decryptKey;
+}
+
+export { type DecryptManyResult, KEY_ADMIN_FACT_TYPE, KEY_DESCRIBE_FACT_TYPE, type KeyCallOptions, type KeyDescriptor, type KeyEncryptOptions, NAMED_KEY_ENVELOPE_VERSION, NamedKeyClient, type NamedKeyClientConfig, type NamedKeyEnvelope, NamedKeyError, type NamedKeyErrorCode, type NamedKeyErrorInit, type NamedKeyInvocationInput, type PublicKeyDescriptor, buildKeyAdminFacts, buildKeyDescribeFacts, mapNodeKeyError, requireKeyTarget, safeEcho };