oro:secure-storage
oro:secure-storage stores secrets scoped by origin (for example tokens, credentials, API keys).
Related guides#
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