index

cifer-sdk API Reference v0.4.1

---

cifer-sdk API Reference / web2

web2

Web2 namespace for email-based registration, session management, and session-first blackbox operations.

Remarks

This namespace provides:

• auth: Registration, email verification, key registration
• session: Managed and existing-key session creation
• secret: Web2 secret creation and listing
• delegate: Delegate management
• permit: Permit requests (rotate/transfer/delegate)
• principal: Principal lookup by email
• blackbox: Session-first wrappers for payload/file/job operations

Namespaces

• web2/auth
• web2/blackbox
• web2/delegate
• web2/permit
• web2/principal
• web2/secret
• web2/session

Interfaces

Web2ClientConfig

Defined in: web2/client.ts:66

Configuration for creating a Web2 client.

Properties

blackboxUrl

blackboxUrl: string

Defined in: web2/client.ts:68

Blackbox URL (e.g. 'https://cifer-blackbox.ternoa.dev:3010')

readClient?

optional readClient: ReadClient

Defined in: web2/client.ts:70

Read client for encrypt/decrypt operations (optional, can be passed per-call)

fetch()?

optional fetch: (input, init?) => Promise<Response>

Defined in: web2/client.ts:72

Custom fetch implementation

MDN Reference

Parameters

input

RequestInfo | URL

init?

RequestInit

Returns

Promise<Response>

---

Web2Client

Defined in: web2/client.ts:106

Web2 client with auto-stored session and defaults.

Remarks

Created via createClient. Wraps the stateless web2.* functions with stored session, blackboxUrl, and readClient so you don't need to pass them on every call.

After calling createManagedSession() or useExistingSessionKey(), the session is stored internally and used for all subsequent operations. You can still override any default per-call.

Example

const client = web2.createClient({ blackboxUrl, readClient });

await client.createManagedSession({ principalId, ed25519Signer });

const secret = await client.createSecret();
const encrypted = await client.payload.encryptPayload({
  secretId: secret.secretId,
  plaintext: 'Hello!',
});

Properties

session

readonly session: Web2Session | null

Defined in: web2/client.ts:108

The currently stored session (null if no session has been created yet)

blackboxUrl

readonly blackboxUrl: string

Defined in: web2/client.ts:110

The configured blackbox URL

readClient

readonly readClient: ReadClient | undefined

Defined in: web2/client.ts:112

The configured read client (may be undefined)

payload

payload: object

Defined in: web2/client.ts:222

encryptPayload()

encryptPayload(params): Promise<EncryptPayloadResult>

Encrypt a payload using the stored session.

Parameters

params

secretId

number | bigint

plaintext

string

outputFormat?

OutputFormat

session?

Web2Session

blackboxUrl?

string

readClient?

ReadClient

fetch?

(input, init?) => Promise<Response>

Returns

Promise<EncryptPayloadResult>

decryptPayload()

decryptPayload(params): Promise<DecryptPayloadResult>

Decrypt a payload using the stored session.

Parameters

params

secretId

number | bigint

encryptedMessage

string

cifer

string

inputFormat?

InputFormat

session?

Web2Session

blackboxUrl?

string

readClient?

ReadClient

fetch?

(input, init?) => Promise<Response>

Returns

Promise<DecryptPayloadResult>

files

files: object

Defined in: web2/client.ts:255

encryptFile()

encryptFile(params): Promise<FileJobResult>

Encrypt a file using the stored session.

Parameters

params

secretId

number | bigint

file

Blob | File

session?

Web2Session

blackboxUrl?

string

readClient?

ReadClient

fetch?

(input, init?) => Promise<Response>

Returns

Promise<FileJobResult>

decryptFile()

decryptFile(params): Promise<FileJobResult>

Decrypt a file using the stored session.

Parameters

params

secretId

number | bigint

file

Blob | File

session?

Web2Session

blackboxUrl?

string

readClient?

ReadClient

fetch?

(input, init?) => Promise<Response>

Returns

Promise<FileJobResult>

decryptExistingFile()

decryptExistingFile(params): Promise<FileJobResult>

Decrypt an existing file using the stored session.

Parameters

params

secretId

number | bigint

encryptJobId

string

session?

Web2Session

blackboxUrl?

string

readClient?

ReadClient

fetch?

(input, init?) => Promise<Response>

Returns

Promise<FileJobResult>

jobs

jobs: object

Defined in: web2/client.ts:297

getStatus()

getStatus(jobId, blackboxUrl?, options?): Promise<JobInfo>

Get job status (no session needed).

Parameters

jobId

string

blackboxUrl?

string

options?

fetch?

(input, init?) => Promise<Response>

Returns

Promise<JobInfo>

pollUntilComplete()

pollUntilComplete(jobId, blackboxUrl?, options?): Promise<JobInfo>

Poll until a job completes (no session needed).

Parameters

jobId

string

blackboxUrl?

string

options?

intervalMs?

number

maxAttempts?

number

onProgress?

(job) => void

fetch?

(input, init?) => Promise<Response>

Returns

Promise<JobInfo>

download()

download(jobId, params): Promise<Blob>

Download a completed job (session needed for decrypt jobs).

Parameters

jobId

string

params

secretId

number | bigint

session?

Web2Session

blackboxUrl?

string

readClient?

ReadClient

fetch?

(input, init?) => Promise<Response>

Returns

Promise<Blob>

deleteJob()

deleteJob(jobId, params): Promise<void>

Delete a job (session needed).

Parameters

jobId

string

params

secretId

number | bigint

session?

Web2Session

blackboxUrl?

string

readClient?

ReadClient

fetch?

(input, init?) => Promise<Response>

Returns

Promise<void>

list()

list(params?): Promise<ListJobsResult>

List all jobs (session needed).

Parameters

params?

includeExpired?

boolean

session?

Web2Session

blackboxUrl?

string

readClient?

ReadClient

fetch?

(input, init?) => Promise<Response>

Returns

Promise<ListJobsResult>

dataConsumption()

dataConsumption(params?): Promise<DataConsumption>

Get data consumption statistics (session needed).

Parameters

params?

session?

Web2Session

blackboxUrl?

string

readClient?

ReadClient

fetch?

(input, init?) => Promise<Response>

Returns

Promise<DataConsumption>

Methods

createManagedSession()

createManagedSession(params): Promise<Web2Session>

Defined in: web2/client.ts:126

Create a managed session and store it in the client.

The blackboxUrl is automatically filled from the client config.

Parameters

params

Session parameters (blackboxUrl is optional, defaults to client config)

principalId

string

ed25519Signer

Ed25519Signer

ttl?

number

blackboxUrl?

string

fetch?

(input, init?) => Promise<Response>

Returns

Promise<Web2Session>

The created Web2Session (also stored internally)

useExistingSessionKey()

useExistingSessionKey(params): Web2Session

Defined in: web2/client.ts:140

Use an existing session key and store it in the client.

Parameters

params

UseExistingSessionKeyParams

Existing session key parameters

Returns

Web2Session

The Web2Session (also stored internally)

setSession()

setSession(session): void

Defined in: web2/client.ts:147

Manually set or replace the stored session.

Parameters

session

Web2Session

The session to store

Returns

void

createSecret()

createSecret(params?): Promise<CreateWeb2SecretResult>

Defined in: web2/client.ts:158

Create a new Web2 secret.

Uses the stored session and blackboxUrl unless overridden.

Parameters

params?

session?

Web2Session

blackboxUrl?

string

fetch?

(input, init?) => Promise<Response>

Returns

Promise<CreateWeb2SecretResult>

listSecrets()

listSecrets(params?): Promise<ListWeb2SecretsResult>

Defined in: web2/client.ts:169

List all Web2 secrets for the current principal.

Uses the stored session and blackboxUrl unless overridden.

Parameters

params?

session?

Web2Session

blackboxUrl?

string

fetch?

(input, init?) => Promise<Response>

Returns

Promise<ListWeb2SecretsResult>

setDelegate()

setDelegate(params): Promise<SetWeb2DelegateResult>

Defined in: web2/client.ts:184

Set or remove a delegate for a Web2 secret.

Uses the stored session and blackboxUrl unless overridden.

Parameters

params

secretId

number | bigint

delegatePrincipalId

string

session?

Web2Session

blackboxUrl?

string

fetch?

(input, init?) => Promise<Response>

Returns

Promise<SetWeb2DelegateResult>

requestPermit()

requestPermit(params): Promise<RequestPermitResult>

Defined in: web2/client.ts:202

Request a permit (rotate, transfer, or delegate).

For transfer/delegate permits, uses the stored session unless overridden. For rotate permits, no session is needed (uses email+password).

Parameters

params

Omit<RequestRotatePermitParams, "blackboxUrl"> & object | Omit<RequestTransferOrDelegatePermitParams, "blackboxUrl" | "session"> & object

Returns

Promise<RequestPermitResult>

getByEmail()

getByEmail(email, blackboxUrl?, options?): Promise<PrincipalByEmailResult>

Defined in: web2/client.ts:216

Look up a principal by email address.

Uses the stored blackboxUrl unless overridden.

Parameters

email

string

blackboxUrl?

string

options?

fetch?

(input, init?) => Promise<Response>

Returns

Promise<PrincipalByEmailResult>

Functions

createClient()

createClient(config): Web2Client

Defined in: web2/client.ts:402

Create a Web2 client with auto-stored session and defaults.

Parameters

config

Web2ClientConfig

Client configuration

Returns

Web2Client

A configured Web2Client instance

Remarks

The client wraps all web2.* functions, storing session, blackboxUrl, and readClient internally. After creating a session via createManagedSession() or useExistingSessionKey(), all subsequent calls automatically use the stored session.

The existing stateless web2.* functions remain available for advanced use cases that need explicit parameter passing.

Example

import { web2 } from 'cifer-sdk';

const client = web2.createClient({
  blackboxUrl: 'https://cifer-blackbox.ternoa.dev:3010',
  readClient: sdk.readClient,
});

// Session is auto-stored
await client.createManagedSession({
  principalId: reg.principalId,
  ed25519Signer,
});

// No session or blackboxUrl needed!
const secret = await client.createSecret();

const encrypted = await client.payload.encryptPayload({
  secretId: secret.secretId,
  plaintext: 'Hello Web2!',
});