@northstartech/cipher 0.0.0-stage → 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,237 @@
+import { CipherError } from './errors.js';
+import { EncryptedObject } from './object.js';
+import { SearchIndex, type SearchIndexInfo } from './search.js';
+/** Object identity bound into every ciphertext. `collection` and `field` are required. */
+export interface CipherContext {
+    collection: string;
+    field: string;
+    recordId?: string | number;
+    [key: string]: string | number | undefined;
+}
+export type Normalization = 'exact' | 'case_insensitive' | 'email' | 'alphanumeric' | 'digits';
+export interface WireEvent {
+    direction: 'request' | 'response';
+    method: string;
+    path: string;
+    status?: number;
+    body: string;
+}
+export interface NorthstarCipherOptions {
+    /** Gateway URL, e.g. `https://api.northstar.mx` (or `http://localhost:7080` locally). */
+    endpoint?: string;
+    /** Workload credential (`nsc_dev_…` / `nsc_live_…`). */
+    credential: string;
+    /** Default key alias. Default `"default"`. */
+    keyId?: string;
+    /** Attestation policy. `auto` = development for `nsc_dev_`, production for `nsc_live_`. */
+    attestation?: 'auto' | 'development' | 'production';
+    /** Pinned verifier keys, `"<kid>:<base64url public key>"`. Required for production. */
+    trustAnchors?: string[];
+    /** Optional allow-list of enclave measurements. */
+    allowedMeasurements?: string[];
+    /** Request timeout. Default 30 000 ms. */
+    timeoutMs?: number;
+    /** Retries for retryable failures. Default 2. */
+    maxRetries?: number;
+    /** Coalesce concurrent `encrypt`/`decrypt` calls into batch requests. Default on. */
+    batching?: boolean | {
+        maxItems?: number;
+    };
+    /** Observe the sealed traffic exactly as the gateway sees it (diagnostics, playground). */
+    debug?: {
+        onWire?: (e: WireEvent) => void;
+    };
+    /** Custom fetch (tests, proxies). */
+    fetch?: typeof fetch;
+}
+export interface EncryptInput {
+    keyId?: string;
+    plaintext: string | Uint8Array;
+    context: CipherContext;
+    /** Generate a blind index for exact-match search (requires `cipher.index`). */
+    index?: boolean | {
+        normalization?: Normalization;
+    };
+}
+export interface EncryptOutput {
+    ciphertext: string;
+    keyId: string;
+    keyVersion: number;
+    /** Blind index token when requested. */
+    index?: string;
+}
+export interface DecryptInput {
+    ciphertext: string;
+    context: CipherContext;
+    purpose?: string;
+}
+export interface DecryptOutput {
+    plaintext: string;
+    bytes: Uint8Array;
+    keyId: string;
+    keyVersion: number;
+}
+export interface EncryptObjectInput {
+    /** Key alias or id that protects the object key. Default: the client's key. */
+    keyId?: string;
+    plaintext: string | Uint8Array;
+    /** Where the wrapped key is stored: `collection`, `field` and `recordId`. */
+    context: CipherContext;
+    /** log2 of the block size, 12 … 24. Default 16 (64 KiB). */
+    blockLog2?: number;
+}
+export interface DecryptObjectInput {
+    /** The NSOB v1 object from `encryptObject()`. */
+    object: Uint8Array;
+    /** The `nsc:v1:` wrapped key stored with the record. */
+    wrappedKey: string;
+    context: CipherContext;
+    purpose?: string;
+}
+export interface SessionDetails {
+    instanceId: string;
+    platform: 'simulated' | 'sev-snp';
+    measurement: string;
+    sessionId: string;
+    expiresAt: Date;
+    scopes: string[];
+}
+export type Settled<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: CipherError;
+};
+/** Normalize a context: camelCase → snake_case keys, values to strings, drop undefined. */
+export declare function wireContext(ctx: CipherContext): Record<string, string>;
+/**
+ * Northstar Cipher client. Create one per process and share it.
+ *
+ * ```ts
+ * const cipher = new NorthstarCipher({ endpoint: process.env.NORTHSTAR_CIPHER_ENDPOINT, credential: process.env.NORTHSTAR_CIPHER_CREDENTIAL! })
+ * const { ciphertext } = await cipher.encrypt({ plaintext: 'G12345678', context: { collection: 'citizens', field: 'passport', recordId: '123' } })
+ * ```
+ */
+export declare class NorthstarCipher {
+    private readonly endpoint;
+    private readonly keyId;
+    private readonly opts;
+    private readonly fetchImpl;
+    private credential?;
+    private token?;
+    private tokenInFlight?;
+    private sessionValue?;
+    private sessionInFlight?;
+    private trustCache;
+    private encryptQueue;
+    private decryptQueue;
+    private flushScheduled;
+    private warnedBatch;
+    constructor(opts: NorthstarCipherOptions);
+    /** Create a client from `NORTHSTAR_CIPHER_*` environment variables (Node.js). */
+    static fromEnv(overrides?: Partial<NorthstarCipherOptions>): NorthstarCipher;
+    private cred;
+    private policy;
+    private wire;
+    private http;
+    private plain;
+    private getToken;
+    private verifierKey;
+    private getSession;
+    private callOnce;
+    private call;
+    private get batchMax();
+    private schedule;
+    private flush;
+    private runEncrypt;
+    private runDecrypt;
+    private batchingEnabled;
+    /** Encrypt one value. Concurrent calls are coalesced into batch requests. */
+    encrypt(input: EncryptInput): Promise<EncryptOutput>;
+    private encryptDirect;
+    private encryptItem;
+    /** Decrypt one value. Concurrent calls are coalesced into batch requests when permitted. */
+    decrypt(input: DecryptInput): Promise<DecryptOutput>;
+    private decryptDirect;
+    /** One `/v1/decrypt`, returning the plaintext as bytes only. */
+    private decryptBytes;
+    /**
+     * Encrypt an object of any size (protocol §13): a random 32-byte object key
+     * seals the bytes here (NSOB v1, AES-256-GCM blocks) and Cipher encrypts only
+     * that key for `context`, in one `/v1/encrypt`. The object never leaves this process.
+     *
+     * ```ts
+     * const context = { collection: 'documents', field: 'file_key', recordId: doc.id }
+     * const { wrappedKey, object } = await cipher.encryptObject({ plaintext: pdf, context })
+     * ```
+     */
+    encryptObject(input: EncryptObjectInput): Promise<EncryptedObject>;
+    /**
+     * Decrypt an object sealed by `encryptObject()`: Cipher decrypts its key for
+     * `context` in one `/v1/decrypt` (policy, purpose and audit as for any decrypt),
+     * then the bytes are opened here. Any tampering raises `INVALID_CIPHERTEXT`.
+     */
+    decryptObject(input: DecryptObjectInput): Promise<Uint8Array>;
+    /** Encrypt many values; throws the first item error. */
+    encryptMany(items: EncryptInput[]): Promise<EncryptOutput[]>;
+    /** Encrypt many values, reporting per-item outcomes. */
+    encryptManySettled(items: EncryptInput[]): Promise<Settled<EncryptOutput>[]>;
+    /** Decrypt many values; throws the first item error. */
+    decryptMany(items: DecryptInput[], opts?: {
+        purpose?: string;
+    }): Promise<DecryptOutput[]>;
+    /**
+     * Decrypt many values, reporting per-item outcomes. Uses `/v1/decrypt/batch`
+     * when the credential holds `cipher.decrypt.batch`; otherwise falls back to
+     * individual requests (bounded concurrency).
+     */
+    decryptManySettled(items: DecryptInput[], opts?: {
+        purpose?: string;
+    }): Promise<Settled<DecryptOutput>[]>;
+    /** Rewrap ciphertexts to the key's current version without exposing plaintext (`cipher.rewrap`). */
+    rewrapMany(items: {
+        ciphertext: string;
+        context: CipherContext;
+    }[], opts?: {
+        jobId?: string;
+    }): Promise<Settled<{
+        ciphertext: string;
+        keyVersion: number;
+        rewrapped: boolean;
+    }>[]>;
+    /** Compute blind indexes for existing ciphertext (backfill / reindex). */
+    indexMany(items: {
+        ciphertext: string;
+        context: CipherContext;
+    }[], opts?: {
+        normalization?: Normalization;
+    }): Promise<Settled<string>[]>;
+    /**
+     * Exact-match search tokens. Returns one list per value: match a row when its
+     * stored blind index equals ANY token in the list (active + query-only index versions).
+     */
+    searchTokens(input: {
+        keyId?: string;
+        collection: string;
+        field: string;
+        values: (string | Uint8Array)[];
+        normalization?: Normalization;
+    }): Promise<string[][]>;
+    /**
+     * A Northstar Search index (encrypted full-text search inside the enclave).
+     * Cheap: no request is made until a method of the index is called.
+     *
+     * ```ts
+     * const customers = cipher.index('customers')
+     * await customers.ensure({ language: 'spanish', fields: { name: 'text', city: 'keyword' } })
+     * await customers.upsert({ 42: { name: 'Ana García', city: 'CDMX' } })
+     * const { hits } = await customers.search({ q: 'ana garsia', filter: { city: 'CDMX' } })
+     * ```
+     */
+    index(name: string): SearchIndex;
+    /** Search indexes this credential may query or write. */
+    searchIndexes(): Promise<SearchIndexInfo[]>;
+    /** Establish (or reuse) the attested session and describe it. */
+    session(): Promise<SessionDetails>;
+}