JavaScript APIs / oro:secure-storage

oro:secure-storage

oro:secure-storage stores secrets scoped by origin (for example tokens, credentials, API keys).

Import#

import * as secureStorage from 'oro:secure-storage'

Store and retrieve a token#

import * as secureStorage from 'oro:secure-storage'

await secureStorage.setItem('authToken', 'secret-token-value')
const token = await secureStorage.getItem('authToken')

Scopes#

By default, secure storage uses location.origin as the scope (when available). You can override the scope explicitly:

await secureStorage.setItem('key', 'value', { scope: 'https://example.com' })

Encodings and binary values#

For strings, encoding may be utf8 (default), base64, or hex.

For binary values, pass a Uint8Array, ArrayBuffer, or Buffer. When reading binary values, use encoding: 'buffer' to get a Uint8Array back.

const bytes = new Uint8Array([1, 2, 3])
await secureStorage.setItem('blob', bytes)

const restored = await secureStorage.getItem('blob', { encoding: 'buffer' })

Inspect existing Android protection#

getStatus() reads existing Keystore metadata without creating a key or decrypting saved values. requiresRecovery means ciphertext exists without its key; preserve it and use explicit recovery. readability: 'not-probed' makes clear that a present key does not prove every value is readable. This metadata probe is Android-only; other platforms reject with ENOSYS.

Use oro:authentication for per-operation cryptographic authentication and oro:credentials for an explicit password-provider chooser. These are separate from secure storage and from server session authorization.

API reference#

Module specifiers#

oro:secure-storage

TypeScript declarations#

These declarations are generated from the runtime's published TypeScript surface.

oro:secure-storage#

declare module "oro:secure-storage" {
    /**
     * Stores a value inside secure storage for the given key.
     * @param {string} key
     * @param {string|Uint8Array|ArrayBuffer|Buffer} value
     * @param {SetItemOptions} [options]
     * @returns {Promise<void>}
     */
    export function setItem(key: string, value: string | Uint8Array | ArrayBuffer | Buffer, options?: SetItemOptions): Promise<void>;
    /**
     * Retrieves a previously stored value.
     * @param {string} key
     * @param {GetItemOptions} [options]
     * @returns {Promise<string|Uint8Array|null>}
     */
    export function getItem(key: string, options?: GetItemOptions): Promise<string | Uint8Array | null>;
    /**
     * Removes a single key from secure storage.
     * @param {string} key
     * @param {SecureStorageOptions} [options]
     * @returns {Promise<void>}
     */
    export function removeItem(key: string, options?: SecureStorageOptions): Promise<void>;
    /**
     * Clears all keys for the provided scope (or default scope).
     * @param {SecureStorageOptions} [options]
     * @returns {Promise<void>}
     */
    export function clear(options?: SecureStorageOptions): Promise<void>;
    /**
     * Lists the stored keys for the provided scope.
     * @param {SecureStorageOptions} [options]
     * @returns {Promise<string[]>}
     */
    export function keys(options?: SecureStorageOptions): Promise<string[]>;
    /**
     * @typedef {object} SecureStorageStatus
     * @property {boolean} available Whether the Android Keystore metadata query succeeded.
     * @property {boolean} keyPresent Whether an existing runtime key was found.
     * @property {'unknown'|'not-created'|'key-missing'|'software'|'hardware'|'tee'|'strongbox'} protection
     * @property {boolean} requiresRecovery Encrypted values exist without their key.
     * @property {boolean|null} userAuthenticationRequired Existing key policy, or null when unknown.
     * @property {'not-probed'} readability No encrypted values were decrypted by this inspection.
     */
    /**
     * Inspects existing Android Keystore protection without creating a key, exporting
     * key material, or decrypting application values. A present key does not prove
     * every stored value is readable. Other platforms reject with ENOSYS.
     * @returns {Promise<SecureStorageStatus>}
     */
    export function getStatus(): Promise<SecureStorageStatus>;
    export default api;
    export type SecureStorageStatus = {
        /**
         * Whether the Android Keystore metadata query succeeded.
         */
        available: boolean;
        /**
         * Whether an existing runtime key was found.
         */
        keyPresent: boolean;
        protection: "unknown" | "not-created" | "key-missing" | "software" | "hardware" | "tee" | "strongbox";
        /**
         * Encrypted values exist without their key.
         */
        requiresRecovery: boolean;
        /**
         * Existing key policy, or null when unknown.
         */
        userAuthenticationRequired: boolean | null;
        /**
         * No encrypted values were decrypted by this inspection.
         */
        readability: "not-probed";
    };
    export type SecureStorageOptions = {
        /**
         * Origin string identifying the storage namespace.
         */
        scope?: string | null;
    };
    export type SetItemOptions = SecureStorageOptions & {
        encoding?: "utf8" | "base64" | "hex";
    };
    export type GetItemOptions = SecureStorageOptions & {
        encoding?: "utf8" | "base64" | "hex" | "buffer";
    };
    export type SecureStorageModule = {
        setItem: typeof setItem;
        getItem: typeof getItem;
        removeItem: typeof removeItem;
        clear: typeof clear;
        keys: typeof keys;
        getStatus: typeof getStatus;
    };
    import { Buffer } from "oro:buffer";
    /**
     * @typedef {Object} SecureStorageModule
     * @property {typeof setItem} setItem
     * @property {typeof getItem} getItem
     * @property {typeof removeItem} removeItem
     * @property {typeof clear} clear
     * @property {typeof keys} keys
     * @property {typeof getStatus} getStatus
     */
    /** @type {SecureStorageModule} */
    const api: SecureStorageModule;
}

See also#

Source repository · Edit this page · View Markdown

Quick links

Type to search across the site. Use the up and down arrow keys to choose a result, Enter to open it, and Escape to close.