ironnode.d.ts

export type Base64String = string;
export type RFC3339Date = string;
export type PrivateKey<T> = T;
export interface PublicKey<T> {
    x: T;
    y: T;
}

export interface DocumentAccessList {
    users?: Array<{id: string}>;
    groups?: Array<{id: string}>;
}
export interface UserCreateOptions {
    needsRotation: boolean;
}
export interface DeviceCreateOptions {
    deviceName: string;
}
export interface DocumentCreateOptions {
    documentID?: string;
    documentName?: string;
    accessList?: DocumentAccessList;
    grantToAuthor?: boolean;
}
export interface GroupCreateOptions {
    groupID?: string;
    groupName?: string;
    addAsMember?: boolean;
    needsRotation?: boolean;
}
export interface GroupUpdateOptions {
    groupName: string | null;
}

export type DocumentAssociation = "owner" | "fromUser" | "fromGroup";
export interface DocumentVisibilityList {
    users: Array<{id: string}>;
    groups: Array<{id: string; name?: string}>;
}

/**
 * Document SDK response types
 */
export interface ApiUserResponse {
    accountID: string;
    segmentID: number;
    userMasterPublicKey: PublicKey<Base64String>;
}
export interface DocumentIDNameResponse {
    documentID: string;
    documentName: string | null;
    created: RFC3339Date;
    updated: RFC3339Date;
}
export interface DocumentAssociationResponse extends DocumentIDNameResponse {
    association: DocumentAssociation;
}
export interface DocumentListResponse {
    result: DocumentAssociationResponse[];
}
export interface DocumentMetaResponse extends DocumentAssociationResponse {
    visibleTo: DocumentVisibilityList;
}
export interface DecryptedDocumentResponse extends DocumentMetaResponse {
    data: Buffer;
}
export interface EncryptedDocumentResponse extends DocumentIDNameResponse {
    document: Buffer;
}
export interface DocumentAccessResponse {
    succeeded: Array<{
        id: string;
        type: "user" | "group";
    }>;
    failed: Array<{
        id: string;
        type: "user" | "group";
        error: string;
    }>;
}

/**
 * Group SDK response types
 */
export interface GroupMetaResponse {
    groupID: string;
    groupName: string | null;
    isAdmin: boolean;
    isMember: boolean;
    created: RFC3339Date;
    updated: RFC3339Date;
}
export interface GroupListResponse {
    result: GroupMetaResponse[];
}
export interface GroupDetailResponse extends GroupMetaResponse {
    groupAdmins: string[];
    groupMembers: string[];
    needsRotation: boolean;
}
export interface GroupUserEditResponse {
    succeeded: string[];
    failed: Array<{
        id: string;
        error: string;
    }>;
}

/**
 * User status as returned by the IronCore Identity server. Typed as `number`
 * instead of `0 | 1` because the wire format is a `u8` and future server releases
 * may introduce new status values; older clients still need to deserialize
 * those responses without a type-system lie. Use the `UserStatus` constants
 * (`UserStatus.Disabled`, `UserStatus.Enabled`) for the values you write,
 * and treat unknown values as opaque on read.
 */
export type UserStatus = number;
export interface UserUpdateResult {
    accountID: string;
    segmentID: number;
    status: UserStatus;
    userMasterPublicKey: PublicKey<Base64String>;
    needsRotation: boolean;
}

export interface UserPublicKeyGetResponse {
    [userID: string]: PublicKey<string> | null;
}
export interface UserDevice {
    id: number;
    name: string | null;
    created: RFC3339Date;
    updated: RFC3339Date;
    publicSigningKey: Base64String;
    isCurrentDevice: boolean;
}
export interface UserDeviceListResponse {
    result: UserDevice[];
}

export interface Document {
    list(): Promise<DocumentListResponse>;
    getMetadata(documentID: string): Promise<DocumentMetaResponse>;
    getDocumentIDFromBytes(encryptedDocument: Buffer): Promise<string | null>;
    getDocumentIDFromStream(encryptedDocument: NodeJS.ReadableStream): Promise<string | null>;
    decryptBytes(documentID: string, encryptedDocument: Buffer): Promise<DecryptedDocumentResponse>;
    encryptBytes(documentData: Buffer, options?: DocumentCreateOptions): Promise<EncryptedDocumentResponse>;
    encryptStream(inputStream: NodeJS.ReadableStream, outputStream: NodeJS.WritableStream, options?: DocumentCreateOptions): Promise<DocumentIDNameResponse>;
    updateEncryptedBytes(documentID: string, newDocumentData: Buffer): Promise<EncryptedDocumentResponse>;
    updateEncryptedStream(documentID: string, inputStream: NodeJS.ReadableStream, outputStream: NodeJS.WritableStream): Promise<DocumentIDNameResponse>;
    updateName(documentID: string, name: string | null): Promise<DocumentIDNameResponse>;
    grantAccess(documentID: string, grantList: DocumentAccessList): Promise<DocumentAccessResponse>;
    revokeAccess(documentID: string, revokeList: DocumentAccessList): Promise<DocumentAccessResponse>;
}

export interface Group {
    list(): Promise<GroupListResponse>;
    get(groupID: string): Promise<GroupMetaResponse | GroupDetailResponse>;
    create(options?: GroupCreateOptions): Promise<GroupDetailResponse>;
    update(groupID: string, options: GroupUpdateOptions): Promise<GroupMetaResponse>;
    rotatePrivateKey(groupID: string): Promise<{needsRotation: boolean}>;
    deleteGroup(groupID: string): Promise<{id: string}>;
    addAdmins(groupID: string, adminList: string[]): Promise<GroupUserEditResponse>;
    removeAdmins(groupID: string, adminList: string[]): Promise<GroupUserEditResponse>;
    addMembers(groupID: string, userList: string[]): Promise<GroupUserEditResponse>;
    removeMembers(groupID: string, userList: string[]): Promise<GroupUserEditResponse>;
}

export interface User {
    getPublicKey(users: string | string[]): Promise<UserPublicKeyGetResponse>;
    listDevices(): Promise<UserDeviceListResponse>;
    deleteDevice(id?: number): Promise<{id: number}>;
    deleteDeviceByPublicSigningKey(publicSigningKey: Base64String): Promise<{id: number}>;
    rotateMasterKey(password: string): Promise<{needsRotation: boolean}>;
    changePassword(currentPassword: string, newPassword: string): Promise<void>;
    disableSelf(): Promise<UserUpdateResult>;
}

export interface SDK {
    document: Document;
    group: Group;
    user: User;
    userContext: {
        userNeedsRotation: boolean;
        groupsNeedingRotation: string[];
    };
}

export class SDKError extends Error {
    constructor(error: Error, code: number);
    code: number;
    rawError: Error;
}

export const ErrorCodes: {[key: string]: number};

/** Device keys in the JSON format shared by all IronCore SDKs. */
export interface DeviceContext {
    accountId: string;
    segmentId: number;
    devicePrivateKey: Base64String;
    /** Ed25519 expanded private key: the 32 byte seed followed by the 32 byte public key. */
    signingPrivateKey: Base64String;
}

/** @deprecated The device format `generateDeviceKeys()` returned before 1.3.0. Use `DeviceContext`. */
export interface LegacyDeviceContext {
    accountID: string;
    segmentID: number;
    deviceKeys: {privateKey: Base64String};
    signingKeys: {privateKey: Base64String};
}

export function initialize(deviceContext: DeviceContext): Promise<SDK>;
/** @deprecated Pass a `DeviceContext`. */
export function initialize(legacyDeviceContext: LegacyDeviceContext): Promise<SDK>;
export function initialize(accountID: string, segmentID: number, privateDeviceKey: Base64String, privateSigningKey: Base64String): Promise<SDK>;

export interface DeviceDetails extends DeviceContext {
    deviceId: number;
    name: string | null;
    created: RFC3339Date;
    lastUpdated: RFC3339Date;
    /** Identifies this device to `deleteDeviceByPublicSigningKey`, matching `UserDevice.publicSigningKey`. */
    publicSigningKey: Base64String;
    /** @deprecated Use `accountId`. */
    accountID: string;
    /** @deprecated Use `segmentId`. */
    segmentID: number;
    /** @deprecated Use `devicePrivateKey`. */
    deviceKeys: {
        publicKey: PublicKey<Base64String>;
        privateKey: Base64String;
    };
    /** @deprecated Use `signingPrivateKey` and `publicSigningKey`. */
    signingKeys: {
        publicKey: Base64String;
        privateKey: Base64String;
    };
}

export namespace User {
    export function verify(jwt: string): Promise<ApiUserResponse | undefined>;
    export function create(jwt: string, password: string, options?: UserCreateOptions): Promise<ApiUserResponse>;
    export function generateDeviceKeys(jwt: string, password: string, options?: DeviceCreateOptions): Promise<DeviceDetails>;
    export function updateStatus(jwt: string, status: (typeof UserStatus)[keyof typeof UserStatus]): Promise<UserUpdateResult>;
    export function deleteDeviceByPublicSigningKey(jwt: string, publicSigningKey: Base64String): Promise<{id: number}>;
}

export const UserStatus: {
    Disabled: 0;
    Enabled: 1;
};