@onshorehq/sdk 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -2
- package/dist/index.d.ts +218 -0
- package/dist/index.js +202 -0
- package/package.json +32 -4
package/README.md
CHANGED
|
@@ -1,3 +1,26 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @onshorehq/sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The Onshore server SDK for Node.js and TypeScript. It stores sensitive values in your in-country vault and gives you tokens back, reveals them as your access rules allow, and covers records, lookups, data subject requests, resident checks, detection, flow checks, client tokens, cloaking for AI and webhook signatures.
|
|
4
|
+
|
|
5
|
+
- No runtime dependencies. Node.js 20 or later.
|
|
6
|
+
- Signs its own credentials (Ed25519), refreshes its access token, batches large requests and retries safely.
|
|
7
|
+
- Reveals fail closed.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install @onshorehq/sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { VaultClient } from "@onshorehq/sdk";
|
|
15
|
+
|
|
16
|
+
const vault = new VaultClient({
|
|
17
|
+
baseUrl: process.env.ONSHORE_URL!,
|
|
18
|
+
serviceAccountId: process.env.ONSHORE_SA_ID!,
|
|
19
|
+
keyId: process.env.ONSHORE_KEY_ID!,
|
|
20
|
+
privateKey: process.env.ONSHORE_PRIVATE_KEY!,
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
const [{ token }] = await vault.tokenize("v_live_1", [{ field: "national_id", value: "AB123456C" }]);
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Full reference: https://docs.onshorevault.com/developers/sdks/node/
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
export interface VaultClientOptions {
|
|
2
|
+
/** Base URL of your vault, for example https://vault.yourbank.ng */
|
|
3
|
+
baseUrl: string;
|
|
4
|
+
serviceAccountId: string;
|
|
5
|
+
keyId: string;
|
|
6
|
+
/** Base64 Ed25519 seed from `rv sa-keygen`. Keep it in your secret store. */
|
|
7
|
+
privateKey: string;
|
|
8
|
+
/** Attempts for retryable failures. Default 4. */
|
|
9
|
+
maxAttempts?: number;
|
|
10
|
+
/** Requests time out after this long. Default 10 seconds. */
|
|
11
|
+
timeoutMs?: number;
|
|
12
|
+
fetch?: typeof fetch;
|
|
13
|
+
}
|
|
14
|
+
export declare class VaultError extends Error {
|
|
15
|
+
status: number;
|
|
16
|
+
code: string;
|
|
17
|
+
policy?: string | undefined;
|
|
18
|
+
requestId?: string | undefined;
|
|
19
|
+
constructor(status: number, code: string, message: string, policy?: string | undefined, requestId?: string | undefined);
|
|
20
|
+
}
|
|
21
|
+
export interface TokenizeItem {
|
|
22
|
+
field: string;
|
|
23
|
+
value: string;
|
|
24
|
+
subject_ref?: string;
|
|
25
|
+
}
|
|
26
|
+
export interface TokenizeResult {
|
|
27
|
+
index: number;
|
|
28
|
+
token?: string;
|
|
29
|
+
existing?: boolean;
|
|
30
|
+
error?: {
|
|
31
|
+
code: string;
|
|
32
|
+
message: string;
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
export interface DetokenizeResult {
|
|
36
|
+
index: number;
|
|
37
|
+
decision?: string;
|
|
38
|
+
value?: string;
|
|
39
|
+
policy?: string;
|
|
40
|
+
error?: {
|
|
41
|
+
code: string;
|
|
42
|
+
message: string;
|
|
43
|
+
policy?: string;
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
export interface DetokenizeItem {
|
|
47
|
+
token: string;
|
|
48
|
+
redaction?: "masked" | "token_only";
|
|
49
|
+
}
|
|
50
|
+
export interface SubjectQuery {
|
|
51
|
+
/** A token, your customer reference, or an exact value (matched through the blind index). */
|
|
52
|
+
query?: string;
|
|
53
|
+
field_type?: string;
|
|
54
|
+
has_reveals?: boolean;
|
|
55
|
+
flagged?: boolean;
|
|
56
|
+
created_after?: string;
|
|
57
|
+
created_before?: string;
|
|
58
|
+
sort?: "created_at" | "field_count" | "last_accessed";
|
|
59
|
+
dir?: "asc" | "desc";
|
|
60
|
+
/** 1 to 200. Default 50. */
|
|
61
|
+
limit?: number;
|
|
62
|
+
offset?: number;
|
|
63
|
+
}
|
|
64
|
+
export interface SubjectSummary {
|
|
65
|
+
id: string;
|
|
66
|
+
ref: string;
|
|
67
|
+
field_count: number;
|
|
68
|
+
created_at: string;
|
|
69
|
+
last_accessed: string | null;
|
|
70
|
+
reveals_30d: number;
|
|
71
|
+
restricted: boolean;
|
|
72
|
+
}
|
|
73
|
+
export interface SubjectField {
|
|
74
|
+
field: string;
|
|
75
|
+
data_type: string;
|
|
76
|
+
token: string;
|
|
77
|
+
masked?: string;
|
|
78
|
+
decision: string;
|
|
79
|
+
record_id: string;
|
|
80
|
+
}
|
|
81
|
+
export interface ExportedField {
|
|
82
|
+
field: string;
|
|
83
|
+
data_type: string;
|
|
84
|
+
value: string;
|
|
85
|
+
token: string;
|
|
86
|
+
decision: string;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Checks a webhook from Onshore. Pass the body exactly as received, before any
|
|
90
|
+
* JSON parsing, and the `x-rv-signature` header. During a secret rotation the header
|
|
91
|
+
* holds two signatures, and either one is enough.
|
|
92
|
+
*/
|
|
93
|
+
export declare function verifyWebhook(secret: string, rawBody: string | Buffer, signatureHeader: string, opts?: {
|
|
94
|
+
toleranceSeconds?: number;
|
|
95
|
+
now?: number;
|
|
96
|
+
}): boolean;
|
|
97
|
+
export declare class VaultClient {
|
|
98
|
+
private opts;
|
|
99
|
+
private key;
|
|
100
|
+
private token;
|
|
101
|
+
private tokenExpiry;
|
|
102
|
+
private fetchFn;
|
|
103
|
+
private maxAttempts;
|
|
104
|
+
private timeoutMs;
|
|
105
|
+
constructor(opts: VaultClientOptions);
|
|
106
|
+
private assertion;
|
|
107
|
+
private bearer;
|
|
108
|
+
private raw;
|
|
109
|
+
private call;
|
|
110
|
+
/** Stores values and returns tokens. Larger inputs are split into 500-item batches. */
|
|
111
|
+
tokenize(vault: string, items: TokenizeItem[], opts?: {
|
|
112
|
+
continueOnError?: boolean;
|
|
113
|
+
dryRun?: boolean;
|
|
114
|
+
}): Promise<TokenizeResult[]>;
|
|
115
|
+
/**
|
|
116
|
+
* Returns values as policy allows. Fails closed: when the vault cannot answer
|
|
117
|
+
* this throws, and it never returns the token as if it were the value.
|
|
118
|
+
*/
|
|
119
|
+
detokenize(vault: string, tokens: (string | DetokenizeItem)[], purpose: string, opts?: {
|
|
120
|
+
continueOnError?: boolean;
|
|
121
|
+
}): Promise<DetokenizeResult[]>;
|
|
122
|
+
insertRecord(vault: string, fields: Record<string, string>, subjectRef?: string): Promise<{
|
|
123
|
+
id: string;
|
|
124
|
+
tokens: Record<string, string>;
|
|
125
|
+
}>;
|
|
126
|
+
/** Reads every field of a record, each as the caller's access rules allow. */
|
|
127
|
+
getRecord(vault: string, id: string, purpose: string): Promise<Record<string, DetokenizeResult>>;
|
|
128
|
+
/** Changes the value behind a new-token-each-time (cell) token. The token stays the same. */
|
|
129
|
+
updateValue(vault: string, token: string, value: string): Promise<void>;
|
|
130
|
+
/** Lists the people in a vault. Needs the `search` action. */
|
|
131
|
+
searchSubjects(vault: string, query?: SubjectQuery): Promise<{
|
|
132
|
+
subjects: SubjectSummary[];
|
|
133
|
+
total: number;
|
|
134
|
+
}>;
|
|
135
|
+
/** One person and their fields, each masked at most. Never returns real values. */
|
|
136
|
+
getSubject(vault: string, subjectId: string): Promise<SubjectSummary & {
|
|
137
|
+
fields: SubjectField[];
|
|
138
|
+
}>;
|
|
139
|
+
/** Exports one person's fields for an access request, as access rules allow. Needs the `export` action. */
|
|
140
|
+
exportSubject(vault: string, subjectId: string, purpose: string): Promise<ExportedField[]>;
|
|
141
|
+
/** While restricted, nothing about the person reveals, whatever the access rules say. */
|
|
142
|
+
restrictSubject(vault: string, subjectId: string, restricted: boolean, purpose: string): Promise<boolean>;
|
|
143
|
+
/** Finds a token without revealing a value. Rate-limited on the server. */
|
|
144
|
+
lookup(vault: string, field: string, value: string): Promise<string>;
|
|
145
|
+
/**
|
|
146
|
+
* Mints a single-use token for a secure component in a browser. `collect` names fields;
|
|
147
|
+
* `reveal` names tokens and needs a purpose. Call this from your server, never the browser.
|
|
148
|
+
*/
|
|
149
|
+
createClientToken(vault: string, opts: {
|
|
150
|
+
kind: "collect" | "reveal";
|
|
151
|
+
origin: string;
|
|
152
|
+
fields?: string[];
|
|
153
|
+
tokens?: string[];
|
|
154
|
+
purpose?: string;
|
|
155
|
+
onBehalfOf?: string;
|
|
156
|
+
subjectRef?: string;
|
|
157
|
+
bindIp?: string;
|
|
158
|
+
ttlSeconds?: number;
|
|
159
|
+
}): Promise<{
|
|
160
|
+
client_token: string;
|
|
161
|
+
expires_at: string;
|
|
162
|
+
}>;
|
|
163
|
+
/** Checks a batch before a job sends it somewhere Onshore cannot sit in the path. Only counts are kept. */
|
|
164
|
+
checkFlow(vault: string, flow: string, text: string): Promise<{
|
|
165
|
+
identifiers: number;
|
|
166
|
+
tokens: number;
|
|
167
|
+
clean: boolean;
|
|
168
|
+
by_type: Record<string, number>;
|
|
169
|
+
}>;
|
|
170
|
+
/** Custom entities apply when `vault` is named. `entities` limits to built-in or custom slugs. */
|
|
171
|
+
detect(text: string, opts?: {
|
|
172
|
+
tokenize?: boolean;
|
|
173
|
+
vault?: string;
|
|
174
|
+
entities?: string[];
|
|
175
|
+
includeShadow?: boolean;
|
|
176
|
+
}): Promise<{
|
|
177
|
+
text?: string;
|
|
178
|
+
ruleset_version?: number;
|
|
179
|
+
entities: {
|
|
180
|
+
type: string;
|
|
181
|
+
start: number;
|
|
182
|
+
end: number;
|
|
183
|
+
score: number;
|
|
184
|
+
custom?: boolean;
|
|
185
|
+
entity_version?: number;
|
|
186
|
+
shadow?: boolean;
|
|
187
|
+
}[];
|
|
188
|
+
}>;
|
|
189
|
+
/**
|
|
190
|
+
* Runs a check in the country and returns only true or false, for example whether
|
|
191
|
+
* a stored name matches one supplied. Needs the `compare` policy action.
|
|
192
|
+
*/
|
|
193
|
+
residentCheck(vault: string, token: string, check: "equals" | "name_match" | "age_at_least" | "amount_at_least", arg: string, purpose: string): Promise<boolean>;
|
|
194
|
+
/**
|
|
195
|
+
* Cloaks text before it goes to a model or any outside service. Pass a saved cloak
|
|
196
|
+
* setting's id, or options inline such as `{ person_name: "synthetic", amount: "band" }`.
|
|
197
|
+
* With `keepDays`, the map back to real values is kept in the vault and `id` returned.
|
|
198
|
+
*/
|
|
199
|
+
cloak(vault: string, text: string, opts?: {
|
|
200
|
+
profileId?: string;
|
|
201
|
+
options?: Record<string, string>;
|
|
202
|
+
keepDays?: number;
|
|
203
|
+
}): Promise<{
|
|
204
|
+
text: string;
|
|
205
|
+
changed: Record<string, number>;
|
|
206
|
+
id?: string;
|
|
207
|
+
}>;
|
|
208
|
+
/** Swaps placeholders and stand-in names back, as far as the caller's policy allows. */
|
|
209
|
+
uncloak(vault: string, id: string, text: string, purpose: string): Promise<{
|
|
210
|
+
text: string;
|
|
211
|
+
decisions: Record<string, string>;
|
|
212
|
+
}>;
|
|
213
|
+
deleteTwin(vault: string, id: string): Promise<Record<string, unknown>>;
|
|
214
|
+
/** Erases everything held on a person. Needs the `delete` action. Returns how many records went. */
|
|
215
|
+
eraseSubject(vault: string, subjectId: string, purpose: string): Promise<{
|
|
216
|
+
erased_records: number;
|
|
217
|
+
}>;
|
|
218
|
+
}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
import crypto from "node:crypto";
|
|
2
|
+
export class VaultError extends Error {
|
|
3
|
+
status;
|
|
4
|
+
code;
|
|
5
|
+
policy;
|
|
6
|
+
requestId;
|
|
7
|
+
constructor(status, code, message, policy, requestId) {
|
|
8
|
+
super(message);
|
|
9
|
+
this.status = status;
|
|
10
|
+
this.code = code;
|
|
11
|
+
this.policy = policy;
|
|
12
|
+
this.requestId = requestId;
|
|
13
|
+
this.name = "VaultError";
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
const BATCH = 500;
|
|
17
|
+
const PKCS8 = Buffer.from("302e020100300506032b657004220420", "hex");
|
|
18
|
+
const b64u = (v) => Buffer.from(v).toString("base64url");
|
|
19
|
+
/**
|
|
20
|
+
* Checks a webhook from Onshore. Pass the body exactly as received, before any
|
|
21
|
+
* JSON parsing, and the `x-rv-signature` header. During a secret rotation the header
|
|
22
|
+
* holds two signatures, and either one is enough.
|
|
23
|
+
*/
|
|
24
|
+
export function verifyWebhook(secret, rawBody, signatureHeader, opts = {}) {
|
|
25
|
+
const parts = (signatureHeader ?? "").split(",").map((p) => p.split("=", 2));
|
|
26
|
+
const at = Number(parts.find(([k]) => k === "t")?.[1]);
|
|
27
|
+
if (!Number.isInteger(at))
|
|
28
|
+
return false;
|
|
29
|
+
const now = opts.now ?? Math.floor(Date.now() / 1000);
|
|
30
|
+
if (Math.abs(now - at) > (opts.toleranceSeconds ?? 300))
|
|
31
|
+
return false;
|
|
32
|
+
const want = crypto.createHmac("sha256", secret).update(`${at}.`).update(rawBody).digest();
|
|
33
|
+
return parts.filter(([k]) => k === "v1").some(([, v]) => {
|
|
34
|
+
const got = Buffer.from(v ?? "", "hex");
|
|
35
|
+
return got.length === want.length && crypto.timingSafeEqual(got, want);
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
export class VaultClient {
|
|
39
|
+
opts;
|
|
40
|
+
key;
|
|
41
|
+
token = null;
|
|
42
|
+
tokenExpiry = 0;
|
|
43
|
+
fetchFn;
|
|
44
|
+
maxAttempts;
|
|
45
|
+
timeoutMs;
|
|
46
|
+
constructor(opts) {
|
|
47
|
+
this.opts = opts;
|
|
48
|
+
this.key = crypto.createPrivateKey({ key: Buffer.concat([PKCS8, Buffer.from(opts.privateKey, "base64")]), format: "der", type: "pkcs8" });
|
|
49
|
+
this.fetchFn = opts.fetch ?? fetch;
|
|
50
|
+
this.maxAttempts = opts.maxAttempts ?? 4;
|
|
51
|
+
this.timeoutMs = opts.timeoutMs ?? 10_000;
|
|
52
|
+
}
|
|
53
|
+
assertion() {
|
|
54
|
+
const now = Math.floor(Date.now() / 1000);
|
|
55
|
+
const head = b64u(JSON.stringify({ alg: "EdDSA", typ: "JWT", kid: this.opts.keyId }));
|
|
56
|
+
const body = b64u(JSON.stringify({ iss: this.opts.serviceAccountId, sub: this.opts.serviceAccountId, aud: "onshore", jti: crypto.randomUUID(), iat: now, exp: now + 120 }));
|
|
57
|
+
return `${head}.${body}.${b64u(crypto.sign(null, Buffer.from(`${head}.${body}`), this.key))}`;
|
|
58
|
+
}
|
|
59
|
+
async bearer() {
|
|
60
|
+
if (this.token && Date.now() < this.tokenExpiry - 60_000)
|
|
61
|
+
return this.token;
|
|
62
|
+
const r = await this.raw("POST", "/v1/auth/token", { assertion: this.assertion() }, null);
|
|
63
|
+
this.token = r.access_token;
|
|
64
|
+
this.tokenExpiry = Date.now() + r.expires_in * 1000;
|
|
65
|
+
return this.token;
|
|
66
|
+
}
|
|
67
|
+
async raw(method, path, body, token, headers = {}) {
|
|
68
|
+
let last;
|
|
69
|
+
for (let attempt = 0; attempt < this.maxAttempts; attempt++) {
|
|
70
|
+
if (attempt > 0)
|
|
71
|
+
await new Promise((r) => setTimeout(r, Math.min(2000, 100 * 2 ** attempt) * (0.5 + Math.random() / 2)));
|
|
72
|
+
let resp;
|
|
73
|
+
try {
|
|
74
|
+
resp = await this.fetchFn(this.opts.baseUrl.replace(/\/$/, "") + path, {
|
|
75
|
+
method,
|
|
76
|
+
headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}), ...headers },
|
|
77
|
+
body: body === undefined ? undefined : JSON.stringify(body),
|
|
78
|
+
signal: AbortSignal.timeout(this.timeoutMs),
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
catch (e) {
|
|
82
|
+
last = new VaultError(0, "network_error", e instanceof Error ? e.name : "request failed");
|
|
83
|
+
continue;
|
|
84
|
+
}
|
|
85
|
+
const data = (await resp.json().catch(() => ({})));
|
|
86
|
+
if (resp.ok)
|
|
87
|
+
return data;
|
|
88
|
+
const err = new VaultError(resp.status, data.error?.code ?? "error", data.error?.message ?? `status ${resp.status}`, data.error?.policy, data.request_id);
|
|
89
|
+
if (resp.status === 401 && token) {
|
|
90
|
+
this.token = null;
|
|
91
|
+
throw err;
|
|
92
|
+
}
|
|
93
|
+
if (resp.status === 429 || resp.status >= 500) {
|
|
94
|
+
last = err;
|
|
95
|
+
continue;
|
|
96
|
+
}
|
|
97
|
+
throw err;
|
|
98
|
+
}
|
|
99
|
+
throw last;
|
|
100
|
+
}
|
|
101
|
+
async call(method, path, body, headers) {
|
|
102
|
+
return this.raw(method, path, body, await this.bearer(), headers);
|
|
103
|
+
}
|
|
104
|
+
/** Stores values and returns tokens. Larger inputs are split into 500-item batches. */
|
|
105
|
+
async tokenize(vault, items, opts = {}) {
|
|
106
|
+
const out = [];
|
|
107
|
+
for (let i = 0; i < items.length; i += BATCH) {
|
|
108
|
+
const r = await this.call("POST", `/v1/vaults/${vault}/tokenize`, { items: items.slice(i, i + BATCH), continue_on_error: opts.continueOnError ?? false, dry_run: opts.dryRun ?? false });
|
|
109
|
+
for (const x of r.results)
|
|
110
|
+
out.push({ ...x, index: x.index + i });
|
|
111
|
+
}
|
|
112
|
+
return out;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Returns values as policy allows. Fails closed: when the vault cannot answer
|
|
116
|
+
* this throws, and it never returns the token as if it were the value.
|
|
117
|
+
*/
|
|
118
|
+
async detokenize(vault, tokens, purpose, opts = {}) {
|
|
119
|
+
const out = [];
|
|
120
|
+
for (let i = 0; i < tokens.length; i += BATCH) {
|
|
121
|
+
const items = tokens.slice(i, i + BATCH).map((t) => (typeof t === "string" ? { token: t } : t));
|
|
122
|
+
const r = await this.call("POST", `/v1/vaults/${vault}/detokenize`, { items, purpose, continue_on_error: opts.continueOnError ?? false });
|
|
123
|
+
for (const x of r.results)
|
|
124
|
+
out.push({ ...x, index: x.index + i });
|
|
125
|
+
}
|
|
126
|
+
return out;
|
|
127
|
+
}
|
|
128
|
+
async insertRecord(vault, fields, subjectRef) {
|
|
129
|
+
return this.call("POST", `/v1/vaults/${vault}/records`, { fields, subject_ref: subjectRef });
|
|
130
|
+
}
|
|
131
|
+
/** Reads every field of a record, each as the caller's access rules allow. */
|
|
132
|
+
async getRecord(vault, id, purpose) {
|
|
133
|
+
return (await this.call("GET", `/v1/vaults/${vault}/records/${encodeURIComponent(id)}`, undefined, { "x-rv-purpose": purpose })).fields;
|
|
134
|
+
}
|
|
135
|
+
/** Changes the value behind a new-token-each-time (cell) token. The token stays the same. */
|
|
136
|
+
async updateValue(vault, token, value) {
|
|
137
|
+
await this.call("PUT", `/v1/vaults/${vault}/tokens/${encodeURIComponent(token)}`, { value });
|
|
138
|
+
}
|
|
139
|
+
/** Lists the people in a vault. Needs the `search` action. */
|
|
140
|
+
async searchSubjects(vault, query = {}) {
|
|
141
|
+
return this.call("POST", `/v1/vaults/${vault}/subjects/search`, query);
|
|
142
|
+
}
|
|
143
|
+
/** One person and their fields, each masked at most. Never returns real values. */
|
|
144
|
+
async getSubject(vault, subjectId) {
|
|
145
|
+
const r = await this.call("GET", `/v1/vaults/${vault}/subjects/${encodeURIComponent(subjectId)}`);
|
|
146
|
+
delete r.request_id;
|
|
147
|
+
return r;
|
|
148
|
+
}
|
|
149
|
+
/** Exports one person's fields for an access request, as access rules allow. Needs the `export` action. */
|
|
150
|
+
async exportSubject(vault, subjectId, purpose) {
|
|
151
|
+
return (await this.call("GET", `/v1/vaults/${vault}/subjects/${encodeURIComponent(subjectId)}/export`, undefined, { "x-rv-purpose": purpose })).fields;
|
|
152
|
+
}
|
|
153
|
+
/** While restricted, nothing about the person reveals, whatever the access rules say. */
|
|
154
|
+
async restrictSubject(vault, subjectId, restricted, purpose) {
|
|
155
|
+
return (await this.call("POST", `/v1/vaults/${vault}/subjects/${encodeURIComponent(subjectId)}/restrict`, { restricted, purpose })).restricted;
|
|
156
|
+
}
|
|
157
|
+
/** Finds a token without revealing a value. Rate-limited on the server. */
|
|
158
|
+
async lookup(vault, field, value) {
|
|
159
|
+
return (await this.call("POST", `/v1/vaults/${vault}/lookup`, { field, value })).token;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Mints a single-use token for a secure component in a browser. `collect` names fields;
|
|
163
|
+
* `reveal` names tokens and needs a purpose. Call this from your server, never the browser.
|
|
164
|
+
*/
|
|
165
|
+
async createClientToken(vault, opts) {
|
|
166
|
+
return this.call("POST", `/v1/vaults/${vault}/client-tokens`, { kind: opts.kind, origin: opts.origin, fields: opts.fields, tokens: opts.tokens, purpose: opts.purpose, on_behalf_of: opts.onBehalfOf, subject_ref: opts.subjectRef, bind_ip: opts.bindIp, ttl_seconds: opts.ttlSeconds });
|
|
167
|
+
}
|
|
168
|
+
/** Checks a batch before a job sends it somewhere Onshore cannot sit in the path. Only counts are kept. */
|
|
169
|
+
async checkFlow(vault, flow, text) {
|
|
170
|
+
return this.call("POST", `/v1/vaults/${vault}/flows/${flow}/check`, { text });
|
|
171
|
+
}
|
|
172
|
+
/** Custom entities apply when `vault` is named. `entities` limits to built-in or custom slugs. */
|
|
173
|
+
async detect(text, opts = {}) {
|
|
174
|
+
return this.call("POST", "/v1/detect", { text, tokenize: opts.tokenize ?? false, vault: opts.vault, entities: opts.entities, include_shadow: opts.includeShadow });
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* Runs a check in the country and returns only true or false, for example whether
|
|
178
|
+
* a stored name matches one supplied. Needs the `compare` policy action.
|
|
179
|
+
*/
|
|
180
|
+
async residentCheck(vault, token, check, arg, purpose) {
|
|
181
|
+
return (await this.call("POST", `/v1/vaults/${vault}/resident/check`, { token, check, arg, purpose })).result;
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* Cloaks text before it goes to a model or any outside service. Pass a saved cloak
|
|
185
|
+
* setting's id, or options inline such as `{ person_name: "synthetic", amount: "band" }`.
|
|
186
|
+
* With `keepDays`, the map back to real values is kept in the vault and `id` returned.
|
|
187
|
+
*/
|
|
188
|
+
async cloak(vault, text, opts = {}) {
|
|
189
|
+
return this.call("POST", `/v1/vaults/${vault}/cloak`, { text, profile_id: opts.profileId, options: opts.options, keep_days: opts.keepDays });
|
|
190
|
+
}
|
|
191
|
+
/** Swaps placeholders and stand-in names back, as far as the caller's policy allows. */
|
|
192
|
+
async uncloak(vault, id, text, purpose) {
|
|
193
|
+
return this.call("POST", `/v1/vaults/${vault}/uncloak`, { id, text, purpose });
|
|
194
|
+
}
|
|
195
|
+
async deleteTwin(vault, id) {
|
|
196
|
+
return this.call("DELETE", `/v1/vaults/${vault}/twins/${id}`);
|
|
197
|
+
}
|
|
198
|
+
/** Erases everything held on a person. Needs the `delete` action. Returns how many records went. */
|
|
199
|
+
async eraseSubject(vault, subjectId, purpose) {
|
|
200
|
+
return this.call("DELETE", `/v1/vaults/${vault}/subjects/${encodeURIComponent(subjectId)}`, undefined, { "x-rv-purpose": purpose });
|
|
201
|
+
}
|
|
202
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,34 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@onshorehq/sdk",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Onshore client for Node.js. No runtime dependencies.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "dist/index.js",
|
|
7
|
+
"types": "dist/index.d.ts",
|
|
8
|
+
"files": [
|
|
9
|
+
"dist",
|
|
10
|
+
"README.md"
|
|
11
|
+
],
|
|
12
|
+
"engines": {
|
|
13
|
+
"node": ">=20"
|
|
14
|
+
},
|
|
15
|
+
"scripts": {
|
|
16
|
+
"build": "tsc -p tsconfig.json",
|
|
17
|
+
"prepublishOnly": "npm run build"
|
|
18
|
+
},
|
|
19
|
+
"devDependencies": {
|
|
20
|
+
"typescript": "^5.6.0",
|
|
21
|
+
"@types/node": "^22.0.0"
|
|
22
|
+
},
|
|
23
|
+
"publishConfig": {
|
|
24
|
+
"access": "public"
|
|
25
|
+
},
|
|
26
|
+
"homepage": "https://docs.onshorevault.com/developers/sdks/node/",
|
|
27
|
+
"keywords": [
|
|
28
|
+
"onshore",
|
|
29
|
+
"data-residency",
|
|
30
|
+
"tokenization",
|
|
31
|
+
"vault",
|
|
32
|
+
"pii"
|
|
33
|
+
]
|
|
34
|
+
}
|