@northstartech/cipher 0.0.0-stage → 1.0.0

package/dist/object.js

@@ -0,0 +1,226 @@
+/**
+ * Object encryption, format NSOB v1 (protocol §13): AES-256-GCM in blocks under
+ * a content key derived from a random per-object key and the object's context.
+ * Pure functions; `NorthstarCipher.encryptObject()` / `decryptObject()` generate
+ * the object key and protect it with Cipher.
+ *
+ * ```
+ * header      = "NSOB" ‖ 0x01 ‖ log2(B) ‖ 0^10 ‖ object_id (16)
+ * content_key = HKDF-SHA-256(object_key, salt = object_id, info = "northstar-cipher/v1/object" ‖ 0x00 ‖ ctx)
+ * block i     = AES-256-GCM(content_key, 0^4 ‖ u64(i), aad = header ‖ u64(i) ‖ u8(last))
+ * ```
+ */
+import { wireContext } from './client.js';
+import { subtle } from './crypto.js';
+import { buf, concat, lp, u32, utf8 } from './encoding.js';
+import { CipherError } from './errors.js';
+const MAGIC = [0x4e, 0x53, 0x4f, 0x42]; // "NSOB"
+const VERSION = 1;
+const HEADER_BYTES = 32;
+const TAG_BYTES = 16;
+const KEY_BYTES = 32;
+const ID_BYTES = 16;
+const MIN_BLOCK_LOG2 = 12;
+const MAX_BLOCK_LOG2 = 24;
+const DEFAULT_BLOCK_LOG2 = 16;
+const INFO = 'northstar-cipher/v1/object';
+const CONTEXT_KEY = /^[a-z][a-z0-9_]{0,63}$/;
+const LONE_SURROGATE = /\p{Cs}/u;
+/**
+ * Result of `NorthstarCipher.encryptObject()`. Store `wrappedKey` with the record
+ * (it is an ordinary `nsc:v1:` ciphertext) and `object` in object storage.
+ * `toString()` and `util.inspect` never show the wrapped key or the object bytes.
+ */
+export class EncryptedObject {
+    /** The object key encrypted by Cipher for the object's context (`nsc:v1:…`). */
+    wrappedKey;
+    /** The NSOB v1 object. */
+    object;
+    keyId;
+    keyVersion;
+    constructor(wrappedKey, object, keyId, keyVersion) {
+        this.wrappedKey = wrappedKey;
+        this.object = object;
+        this.keyId = keyId;
+        this.keyVersion = keyVersion;
+    }
+    toString() {
+        return `EncryptedObject { wrappedKey: [ciphertext], object: ${this.object.length} bytes, keyId: ${this.keyId}, keyVersion: ${this.keyVersion} }`;
+    }
+}
+Object.defineProperty(EncryptedObject.prototype, Symbol.for('nodejs.util.inspect.custom'), {
+    value(_depth, options, inspect) {
+        const shown = { wrappedKey: '[ciphertext]', object: `${this.object.length} bytes`, keyId: this.keyId, keyVersion: this.keyVersion };
+        return inspect ? `EncryptedObject ${inspect(shown, options)}` : this.toString();
+    },
+});
+/**
+ * Seal `plaintext` under `objectKey` (32 random bytes, never reused) for `context`.
+ * `objectId` is 16 random bytes; `blockLog2` is 12 … 24 (default 16, 64 KiB blocks).
+ */
+export async function sealObject(objectKey, objectId, context, plaintext, blockLog2 = DEFAULT_BLOCK_LOG2) {
+    checkKey(objectKey);
+    if (!(objectId instanceof Uint8Array) || objectId.length !== ID_BYTES)
+        throw new CipherError('INVALID_REQUEST', 'object id must be 16 bytes');
+    checkBlockLog2(blockLog2);
+    if (typeof plaintext !== 'string' && !(plaintext instanceof Uint8Array))
+        throw new CipherError('INVALID_REQUEST', 'plaintext must be a string or a Uint8Array');
+    const ctx = canonicalContext(context);
+    const bytes = typeof plaintext === 'string' ? utf8(plaintext) : plaintext;
+    // WebCrypto takes ArrayBuffer-backed views; anything else is copied, and every copy is wiped.
+    const pt = (bytes.buffer instanceof ArrayBuffer ? bytes : buf(bytes));
+    try {
+        const block = 2 ** blockLog2;
+        const n = Math.max(1, Math.ceil(pt.length / block));
+        if (n >= 2 ** 32)
+            throw new CipherError('INVALID_REQUEST', 'object is too large for this block size');
+        const header = new Uint8Array(HEADER_BYTES);
+        header.set(MAGIC);
+        header[4] = VERSION;
+        header[5] = blockLog2;
+        header.set(objectId, 16);
+        const key = await deriveContentKey(objectKey, objectId, ctx, 'encrypt');
+        const out = new Uint8Array(HEADER_BYTES + pt.length + TAG_BYTES * n);
+        out.set(header);
+        for (let i = 0; i < n; i++) {
+            const sealed = new Uint8Array(await subtle().encrypt(blockParams(header, i, i === n - 1), key, pt.subarray(i * block, (i + 1) * block)));
+            out.set(sealed, HEADER_BYTES + i * (block + TAG_BYTES));
+        }
+        return out;
+    }
+    finally {
+        if (pt !== plaintext)
+            pt.fill(0);
+    }
+}
+/**
+ * Open an NSOB v1 object. Every block is authenticated before the plaintext is
+ * returned. Any failure is `INVALID_CIPHERTEXT` with one message.
+ */
+export async function openObject(objectKey, context, object) {
+    checkKey(objectKey);
+    const ctx = canonicalContext(context);
+    if (!(object instanceof Uint8Array) ||
+        object.length < HEADER_BYTES ||
+        MAGIC.some((b, i) => object[i] !== b) ||
+        object[4] !== VERSION ||
+        object[5] < MIN_BLOCK_LOG2 ||
+        object[5] > MAX_BLOCK_LOG2 ||
+        object.subarray(6, 16).some((b) => b !== 0)) {
+        throw invalidObject();
+    }
+    const header = object.slice(0, HEADER_BYTES);
+    const stride = 2 ** header[5] + TAG_BYTES;
+    const body = object.length - HEADER_BYTES;
+    if (body < TAG_BYTES)
+        throw invalidObject();
+    const n = Math.ceil(body / stride);
+    const last = body - (n - 1) * stride;
+    if (last < TAG_BYTES || last > stride)
+        throw invalidObject();
+    const src = (object.buffer instanceof ArrayBuffer ? object : buf(object)); // WebCrypto takes ArrayBuffer-backed views
+    const key = await deriveContentKey(objectKey, header.subarray(16), ctx, 'decrypt');
+    const out = new Uint8Array(body - TAG_BYTES * n);
+    try {
+        for (let i = 0; i < n; i++) {
+            const start = HEADER_BYTES + i * stride;
+            let pt;
+            try {
+                pt = new Uint8Array(await subtle().decrypt(blockParams(header, i, i === n - 1), key, src.subarray(start, start + (i === n - 1 ? last : stride))));
+            }
+            catch {
+                throw invalidObject();
+            }
+            out.set(pt, i * (stride - TAG_BYTES));
+            pt.fill(0);
+        }
+        return out;
+    }
+    catch (e) {
+        out.fill(0);
+        throw e;
+    }
+}
+/**
+ * The content key (32 bytes): HKDF-SHA-256(object_key, salt = object_id,
+ * info = "northstar-cipher/v1/object" ‖ 0x00 ‖ canonical context). For the vectors.
+ */
+export async function objectContentKey(objectKey, objectId, context) {
+    checkKey(objectKey);
+    if (!(objectId instanceof Uint8Array) || objectId.length !== ID_BYTES)
+        throw new CipherError('INVALID_REQUEST', 'object id must be 16 bytes');
+    const { base, params } = await hkdf(objectKey, objectId, canonicalContext(context));
+    return new Uint8Array(await subtle().deriveBits(params, base, 256));
+}
+/**
+ * Canonical context bytes (protocol §3.1): u32(count) ‖ for each (k, v) sorted by k: lp(k) ‖ lp(v).
+ * camelCase keys become snake_case and `undefined`/`null` values are dropped, as for every request.
+ */
+export function canonicalContext(context) {
+    const ctx = wireContext(context);
+    const keys = Object.keys(ctx);
+    if (keys.length < 1 || keys.length > 16)
+        throw new CipherError('INVALID_CONTEXT', 'context must have 1 to 16 entries');
+    const entries = keys.map((k) => {
+        const v = ctx[k];
+        const value = utf8(v);
+        if (!CONTEXT_KEY.test(k) || LONE_SURROGATE.test(v) || value.length < 1 || value.length > 512) {
+            throw new CipherError('INVALID_CONTEXT', 'context keys must be snake_case and values 1–512 bytes of UTF-8');
+        }
+        return { key: utf8(k), value };
+    });
+    entries.sort((a, b) => compareBytes(a.key, b.key));
+    return concat(u32(entries.length), ...entries.flatMap((e) => [lp(e.key), lp(e.value)]));
+}
+/** Size of the object for a plaintext of `length` bytes. */
+export function objectLength(length, blockLog2 = DEFAULT_BLOCK_LOG2) {
+    checkBlockLog2(blockLog2);
+    if (!Number.isSafeInteger(length) || length < 0)
+        throw new CipherError('INVALID_REQUEST', 'length must be a non-negative integer');
+    return HEADER_BYTES + length + TAG_BYTES * Math.max(1, Math.ceil(length / 2 ** blockLog2));
+}
+async function hkdf(objectKey, objectId, ctx) {
+    const raw = buf(objectKey);
+    try {
+        const base = await subtle().importKey('raw', raw, 'HKDF', false, ['deriveBits', 'deriveKey']);
+        return { base, params: { name: 'HKDF', hash: 'SHA-256', salt: buf(objectId), info: buf(concat(utf8(INFO), new Uint8Array([0]), ctx)) } };
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+/** The content key as a non-extractable AES-256-GCM key. */
+async function deriveContentKey(objectKey, objectId, ctx, usage) {
+    const { base, params } = await hkdf(objectKey, objectId, ctx);
+    return subtle().deriveKey(params, base, { name: 'AES-GCM', length: 256 }, false, [usage]);
+}
+/** nonce = 0^4 ‖ u64(i), aad = header ‖ u64(i) ‖ u8(last). */
+function blockParams(header, i, last) {
+    const iv = new Uint8Array(12);
+    new DataView(iv.buffer).setBigUint64(4, BigInt(i));
+    const aad = new Uint8Array(HEADER_BYTES + 9);
+    aad.set(header);
+    new DataView(aad.buffer).setBigUint64(HEADER_BYTES, BigInt(i));
+    aad[HEADER_BYTES + 8] = last ? 1 : 0;
+    return { name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 };
+}
+function checkKey(objectKey) {
+    if (!(objectKey instanceof Uint8Array) || objectKey.length !== KEY_BYTES)
+        throw new CipherError('INVALID_REQUEST', 'object key must be 32 bytes');
+}
+function checkBlockLog2(blockLog2) {
+    if (!Number.isInteger(blockLog2) || blockLog2 < MIN_BLOCK_LOG2 || blockLog2 > MAX_BLOCK_LOG2) {
+        throw new CipherError('INVALID_REQUEST', 'block size must be 2^12 … 2^24 bytes');
+    }
+}
+function compareBytes(a, b) {
+    for (let i = 0; i < Math.min(a.length, b.length); i++)
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    return a.length - b.length;
+}
+/** The single error for every failure to open an object (also a wrapped key that is not an object key). */
+export function invalidObject() {
+    return new CipherError('INVALID_CIPHERTEXT', 'object could not be decrypted (corrupted, truncated, or wrong key or context)');
+}
+//# sourceMappingURL=object.js.map

package/dist/object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.js","sourceRoot":"","sources":["../src/object.ts"],"names":[],"mappings":"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"}

package/dist/search.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Northstar Search: encrypted full-text search that runs inside the attested
+ * enclave. Index files are encrypted at rest under a key only the enclave can
+ * unwrap; documents and queries travel sealed to the enclave session.
+ *
+ * ```ts
+ * const customers = cipher.index('customers')
+ * await customers.ensure({ language: 'spanish', fields: { name: 'text', email: 'keyword', city: 'keyword', balance: 'number' } })
+ * await customers.upsert({ 42: { name: 'Ana García', city: 'CDMX', balance: 1500 } })
+ * const r = await customers.search({ q: 'ana garsia', filter: { city: 'cdmx' } })
+ * // r.hits = [{ id: '42', score: 3.1 }], r.total = 1
+ * ```
+ *
+ * Values may be ciphertexts: a string starting with `nsc:v1:` is decrypted in
+ * the enclave with context (index or `collection`, field, id), or pass
+ * `SearchIndex.ciphertext(ct, context)` to give the context explicitly.
+ */
+import { type CipherContext } from './client.js';
+import { CipherError } from './errors.js';
+export type SearchFieldType = 'text' | 'keyword' | 'integer' | 'number' | 'date' | 'bool';
+export type SearchLanguage = 'english' | 'spanish' | 'portuguese' | 'french' | 'german' | 'italian' | 'dutch' | 'none';
+export interface SearchField {
+    name: string;
+    type: SearchFieldType;
+    /** Relevance weight of a text field, in (0, 100]. */
+    boost?: number;
+    /** Stemming language of a text field (default: the schema's). */
+    language?: SearchLanguage;
+}
+/** Schema in wire form. */
+export interface SearchSchema {
+    language?: SearchLanguage;
+    fields: SearchField[];
+}
+/** Schema accepted by `ensure()`: fields as a list, or as a map `{ name: 'text', city: { type: 'keyword' } }`. */
+export interface SearchSchemaInput {
+    language?: SearchLanguage;
+    fields: SearchField[] | Record<string, SearchFieldType | Omit<SearchField, 'name'>>;
+}
+/** A field value the enclave decrypts before indexing (see {@link SearchIndex.ciphertext}). */
+export interface SearchCiphertext {
+    ciphertext: string;
+    context: Record<string, string>;
+}
+export type SearchScalar = string | number | boolean | Date | null;
+/** A field value: a scalar, a list of scalars, or a ciphertext. Dates as `Date`, RFC 3339 / `YYYY-MM-DD` strings or epoch ms. */
+export type SearchValue = SearchScalar | SearchScalar[] | SearchCiphertext;
+export type SearchFields = Record<string, SearchValue | undefined>;
+export interface SearchDocument {
+    id: string | number;
+    fields: SearchFields;
+}
+export interface SearchIndexVersion {
+    version: number;
+    state: 'active' | 'building';
+    /** Searchable documents (as of the last commit). */
+    documents: number;
+    /** Encrypted bytes on disk. */
+    diskBytes: number;
+    createdAt: Date;
+    schema: SearchSchema;
+}
+export interface SearchIndexInfo {
+    index: string;
+    /** Key protecting the index. */
+    keyId: string;
+    createdAt: Date;
+    /** Last write committed. */
+    updatedAt: Date;
+    /** Live version (queries). */
+    active: SearchIndexVersion;
+    /** Version being built (receives writes too). */
+    building?: SearchIndexVersion;
+    /** `ensure()`: `created` | `unchanged` | `rebuilding`; `activate()`: `activated`. */
+    outcome?: 'created' | 'unchanged' | 'rebuilding' | 'activated';
+}
+export type SearchWriteMode = 'replace' | 'merge';
+/** A raw write (`write()`): any of upserts, deletions, `wait`, `optimize`. */
+export interface SearchWriteRequest {
+    /** Documents to add or update (≤ 5 000 documents and deletions per request). */
+    upsert?: SearchDocument[];
+    delete?: (string | number)[];
+    /** `replace` (default) or `merge` (only the given fields change; `null` removes one). */
+    mode?: SearchWriteMode;
+    /** Context collection of `nsc:v1:` shorthand values (default: the index name). */
+    collection?: string;
+    /** Return once everything written is searchable. */
+    wait?: boolean;
+    /** Merge index segments after this write (end of a bulk load). */
+    optimize?: boolean;
+}
+export interface SearchWriteResult {
+    upserted: number;
+    deleted: number;
+    /** Ciphertext values decrypted inside the enclave. */
+    decrypted: number;
+    /** Documents that were not indexed (the others were). */
+    errors: {
+        id: string;
+        error: CipherError;
+    }[];
+    /** Already searchable (`wait`); otherwise within about a second. */
+    committed: boolean;
+}
+export type SearchFilterValue = string | number | boolean | Date;
+/** A value, any of a list, a range, presence, or exclusion. */
+export type SearchFilter = SearchFilterValue | SearchFilterValue[] | {
+    gt?: SearchFilterValue;
+    gte?: SearchFilterValue;
+    lt?: SearchFilterValue;
+    lte?: SearchFilterValue;
+} | {
+    exists: boolean;
+} | {
+    not: SearchFilterValue | SearchFilterValue[];
+};
+export interface SearchQuery {
+    /** Free text (`"quoted phrases"` supported). Empty: every document. */
+    q?: string;
+    /** Fields to search (default: every text and keyword field). */
+    fields?: string[];
+    /** Typo tolerance (default `auto`). */
+    fuzzy?: 'auto' | 'off' | 'one' | 'two';
+    /** Treat the last word as a prefix (search-as-you-type). Default true. */
+    prefix?: boolean;
+    /** Every word must match (`all`, default) or any. */
+    mode?: 'all' | 'any';
+    filter?: Record<string, SearchFilter>;
+    /** Default: relevance. `_score` sorts by relevance. */
+    sort?: {
+        field: string;
+        desc?: boolean;
+    }[];
+    /** 0–1 000 (0: counts and facets only). Default 20. */
+    limit?: number;
+    /** ≤ 10 000. */
+    offset?: number;
+    /** Keyword fields to count values for. */
+    facets?: string[];
+    /** Buckets per facet (≤ 100, default 10). */
+    facetLimit?: number;
+    /** Fields to return with each hit (`['*']`: every field). Returning values is a decryption. */
+    select?: string[];
+    /** Text/keyword fields to return with matches wrapped in `<mark>` (HTML-escaped). */
+    highlight?: string[];
+    /** Why plaintext is returned (`select` / `highlight`), recorded in the audit log and matched by policy. */
+    purpose?: string;
+}
+export interface SearchHit {
+    id: string;
+    /** Relevance (relevance order only). */
+    score?: number;
+    /** Selected fields. */
+    fields?: Record<string, unknown>;
+    /** Highlighted fragments: field → HTML with matches in `<mark>`. */
+    highlights?: Record<string, string>;
+}
+export interface SearchResult {
+    hits: SearchHit[];
+    /** Total matching documents. */
+    total: number;
+    /** Facet counts: field → buckets. */
+    facets: Record<string, {
+        value: string;
+        count: number;
+    }[]>;
+    /** Engine time. */
+    tookMs: number;
+}
+/** @internal How a {@link SearchIndex} reaches the enclave (the client's sealed `call`). */
+export interface SearchTransport {
+    call<T>(path: string, payload: unknown): Promise<T>;
+    readonly keyId: string;
+}
+interface WireVersion {
+    version: number;
+    state: 'active' | 'building';
+    documents: number;
+    disk_bytes: number;
+    created_at: number;
+    schema: SearchSchema;
+}
+interface WireInfo {
+    index: string;
+    key_id: string;
+    created_at: number;
+    updated_at: number;
+    active: WireVersion;
+    building?: WireVersion;
+    outcome?: SearchIndexInfo['outcome'];
+}
+/** @internal */
+export declare function indexInfo(r: WireInfo): SearchIndexInfo;
+/**
+ * A Northstar Search index. Get one with `cipher.index(name)`; the handle is
+ * cheap and does no I/O until a method is called.
+ */
+export declare class SearchIndex {
+    #private;
+    readonly name: string;
+    /** @internal Use `cipher.index(name)`. */
+    constructor(transport: SearchTransport, name: string);
+    /**
+     * A field value the enclave decrypts before indexing, with an explicit context
+     * (normalized like `encrypt`'s: `recordId` → `record_id`, values as strings).
+     */
+    static ciphertext(ciphertext: string, context: CipherContext): SearchCiphertext;
+    /** Normalize a schema: the map shorthand `{ fields: { name: 'text' } }` becomes the wire list form. */
+    static schema(input: SearchSchemaInput): SearchSchema;
+    /**
+     * Create the index, or confirm it exists with this schema (`outcome`:
+     * `created` | `unchanged`). A different schema fails with `CONFLICT` unless
+     * `rebuild` is set: then a fresh version is built next to the live one
+     * (writes reach both, queries keep using the live one until {@link activate}).
+     * `key`: key alias or id protecting the index (default: the client's key).
+     */
+    ensure(schema: SearchSchemaInput, opts?: {
+        key?: string;
+        rebuild?: boolean;
+    }): Promise<SearchIndexInfo>;
+    describe(): Promise<SearchIndexInfo>;
+    /** Make the version being built (or `version`) live; the previous one is deleted. */
+    activate(version?: number): Promise<SearchIndexInfo>;
+    /** Delete the index and its files. `false` when there was none. */
+    drop(): Promise<boolean>;
+    /**
+     * Add or replace documents: `[{ id, fields }]` or `{ [id]: fields }`. Sent in
+     * chunks of 1 000; `wait` applies to the last chunk (so to all of them).
+     * Rejected documents are listed in `errors`; the others are indexed.
+     */
+    upsert(documents: SearchDocument[] | Record<string, SearchFields>, opts?: {
+        mode?: SearchWriteMode;
+        wait?: boolean;
+        collection?: string;
+    }): Promise<SearchWriteResult>;
+    /** Remove documents by id (absent ids are ignored). */
+    delete(ids: (string | number)[], opts?: {
+        wait?: boolean;
+    }): Promise<SearchWriteResult>;
+    /** Wait until everything written so far is searchable; `optimize` also merges segments (after bulk loads). */
+    flush(opts?: {
+        optimize?: boolean;
+    }): Promise<SearchWriteResult>;
+    /** Raw write (≤ 5 000 documents and deletions): `upsert`, `delete`, `mode`, `collection`, `wait`, `optimize`. */
+    write(request: SearchWriteRequest): Promise<SearchWriteResult>;
+    private send;
+    /** Search. Without `q`, every document matches (filters, facets and sorting still apply). */
+    search(query?: SearchQuery): Promise<SearchResult>;
+}
+export {};