SDK Reference

Two SDK packages provide Sign It functionality for different integration patterns:

Package	Use Case	How It Signs
@flowsta/auth	Web apps using OAuth	API call with OAuth token — server signs via conductor
@flowsta/holochain	Desktop Holochain apps	IPC call to Flowsta Vault — Vault signs locally

@flowsta/auth — Web App Signing

For web apps that use "Sign in with Flowsta" (OAuth). Requires the sign scope.

hashFile(file)

Hash a file using SHA-256 in the browser via SubtleCrypto. The file is never uploaded.

import { hashFile } from '@flowsta/auth';

const file = document.querySelector('input[type=file]').files[0];
const hash = await hashFile(file);
// hash = "a7f3b9c1e2d4..." (64 hex characters)

Parameter	Type	Required	Description
file	File	Yes	File object from file input or drag-and-drop

Returns: Promise<string> — hex-encoded SHA-256 hash (64 characters)

---

signFile(options)

Sign a file hash. The file is never uploaded — only the hash is sent to the API.

const result = await flowsta.signFile({
  fileHash: hash,
  intent: 'authorship',
  aiGeneration: 'none',
  contentRights: {
    license: 'cc-by',
    aiTraining: 'not_allowed',
    contactPreference: 'allow_contact_requests',
  },
});
console.log('Signed:', result.action_hash);

Parameter	Type	Required	Description
fileHash	string	Yes	SHA-256 hex string (64 characters)
intent	string	No	Authorship, Approval, Witness, Receipt, Agreement. Default: Authorship
aiGeneration	string	No	none, assisted, generated
contentRights	object	No	See Content Rights for all fields

Returns:

Field	Type	Description
success	boolean	true on success
file_hash	string	The hash that was signed
agent_pub_key	string	Signer's Holochain agent key (uhCAk... format)
signed_at	number	Unix timestamp in milliseconds
action_hash	string | null	DHT action hash (hex)

Requires: sign scope

---

signBatch(options)

Sign multiple file hashes in one request. Each file gets its own signature on the DHT.

const result = await flowsta.signBatch({
  files: [
    { fileHash: hash1 },
    { fileHash: hash2, intent: 'approval' },
  ],
  sharedMetadata: {
    intent: 'authorship',
    aiGeneration: 'none',
    contentRights: { license: 'all-rights-reserved' },
  },
});
console.log(`Signed ${result.signed}, failed ${result.failed}`);

Parameter	Type	Required	Description
files	array	Yes	Array of { fileHash, intent?, aiGeneration?, contentRights? }. Max 100 files
sharedMetadata	object	No	Applied to all files unless overridden per-file

Returns:

Field	Type	Description
results	array	Per-file results: { file_hash, action_hash, success, error? }
signed	number	Count of successfully signed files
failed	number	Count of failed files

Requires: sign scope

---

verifyFile(fileHash)

Check if a file has been signed. Public endpoint — no authentication required, but authenticated requests with verify scope get higher rate limits.

const result = await flowsta.verifyFile(hash);
if (result.count > 0) {
  result.signatures.forEach(sig => {
    console.log(`Signed by ${sig.signer} on ${new Date(sig.signed_at)}`);
    console.log(`License: ${sig.content_rights?.license}`);
  });
}

Parameter	Type	Required	Description
fileHash	string	Yes	SHA-256 hex string (64 characters)

Returns:

Field	Type	Description
signatures	array	Array of signature objects (see Verification API)
count	number	Total number of signatures

---

getContentRights(fileHash)

Convenience wrapper over verifyFile() that returns just the content rights info.

const rights = await flowsta.getContentRights(hash);
if (rights.signed) {
  rights.rights.forEach(r => {
    console.log(`${r.signer}: ${r.license}, AI training: ${r.aiTraining}`);
  });
}

Returns:

Field	Type	Description
signed	boolean	Whether the file has any signatures
signerCount	number	Total number of signers
rights	array	Array of { signer, license?, aiTraining?, commercialLicensing?, contactPreference?, aiGeneration? }

---

@flowsta/holochain — Desktop App Signing

For Holochain apps that run alongside Flowsta Vault. Signs via IPC — the user approves in Vault.

signDocument(options)

Request Vault to sign a file hash. Shows an approval dialog in Vault.

import { signDocument } from '@flowsta/holochain';

const result = await signDocument({
  clientId: 'flowsta_app_abc123...',
  appName: 'ArtStudio',
  fileHash: 'a7f3b9c1e2d4...',
  label: 'Illustration.png',
  intent: 'authorship',
  contentRights: {
    license: 'cc-by',
    aiTraining: 'not_allowed',
    contactPreference: 'allow_contact_requests',
  },
});

Parameter	Type	Required	Description
clientId	string	Yes	Your app's client ID from dev.flowsta.com
appName	string	Yes	Shown in Vault approval dialog
fileHash	string	Yes	SHA-256 hex string (64 characters)
label	string	No	Human-readable file name for the dialog
intent	string	No	authorship, approval, witness, receipt, agreement
aiGeneration	string	No	none, assisted, generated
contentRights	object	No	See Content Rights
ipcUrl	string	No	Default: http://127.0.0.1:27777

Returns:

Field	Type	Description
success	boolean	true if signed
fileHash	string	The hash that was signed
signature	string	Base64 Ed25519 signature
agentPubKey	string	Signer's agent key (uhCAk... format)
signedAt	string	ISO 8601 timestamp
actionHash	string | null	DHT action hash

Errors:

Error Class	When
VaultNotFoundError	Vault is not running
VaultLockedError	Vault is locked
UserDeniedError	User rejected the signing request
SigningDnaNotInstalledError	Signing DNA not available in Vault

---

getSigningStatus(ipcUrl?)

Check if Vault is available for document signing.

import { getSigningStatus } from '@flowsta/holochain';

const status = await getSigningStatus();
if (status.available) {
  // Show "Sign with Flowsta" button
}

Returns:

Field	Type	Description
available	boolean	true if Vault is running, unlocked, and ready to sign
vaultRunning	boolean	true if Vault IPC server is reachable
vaultUnlocked	boolean	true if Vault is unlocked

---

Content Rights Object

Used by both @flowsta/auth and @flowsta/holochain:

Field	Type	Values
license	string	all-rights-reserved, cc0, cc-by, cc-by-sa, cc-by-nc, cc-by-nc-sa, mit, apache-2, gpl-3
commercialLicensing	string	not_available, open_to_licensing
aiTraining	string	allowed, allowed_with_attribution, requires_license, not_allowed
contactPreference	string	no_contact, allow_contact_requests

All fields are optional. Only declared fields are recorded in the signature.