trustplane-sdk 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# Trustplane JS SDK (v0.1)
+
+Minimal SDK to generate Trustplane proof headers.
+
+## Install
+
+```bash
+npm install trustplane-sdk
+```
+
+## Usage
+
+```js
+const { sign } = require('trustplane-sdk');
+
+const out = sign({
+  tenantId: 'mergematter.io',
+  apiId: 'api_demo',
+  clientId: 'client_demo',
+  privateKey: '<private_key_b64url>',
+  method: 'GET',
+  path: '/orders',
+  body: ''
+});
+
+console.log(out.headers);
+```
+
+## Browser (async)
+
+```js
+import { signAsync } from "trustplane-sdk";
+
+const out = await signAsync({
+  tenantId: "mergematter.io",
+  apiId: "api_demo",
+  clientId: "client_demo",
+  privateKey: "<private_key_b64url>",
+  method: "GET",
+  path: "/orders",
+  body: ""
+});
+```
+
+## Config file
+
+```js
+const { fromFile } = require('trustplane-sdk');
+
+const client = fromFile('./trustplane.json');
+const out = client.sign({
+  method: 'GET',
+  path: '/orders',
+  body: '',
+  privateKey: '<private_key_b64url>'
+});
+```

package/index.d.ts

@@ -0,0 +1,44 @@
+export type SignInput = {
+  tenantId: string;
+  apiId: string;
+  clientId: string;
+  privateKey: string;
+  method?: string;
+  path: string;
+  body?: string;
+  bucketSeconds?: number;
+  timeBucketOverride?: number;
+  nonceOverride?: string;
+};
+
+export type SignOutput = {
+  headers: Record<string, string>;
+  verifyPayload: {
+    tenant_id: string;
+    api_id: string;
+    client_id: string;
+    method: string;
+    path: string;
+    body_hash: string;
+    time_bucket: number;
+    nonce: string;
+    signature: string;
+  };
+  transcript: string;
+  digest: string;
+};
+
+export function sign(input: SignInput): SignOutput;
+export function signAsync(input: SignInput): Promise<SignOutput>;
+
+export function createClient(input: {
+  tenantId: string;
+  apiId: string;
+  clientId: string;
+  bucketSeconds?: number;
+}): {
+  sign(input: Omit<SignInput, "tenantId" | "apiId" | "clientId" | "bucketSeconds">): SignOutput;
+  signAsync(input: Omit<SignInput, "tenantId" | "apiId" | "clientId" | "bucketSeconds">): Promise<SignOutput>;
+};
+
+export function fromFile(path: string): ReturnType<typeof createClient>;

package/index.js

@@ -0,0 +1,209 @@
+const crypto = require('crypto');
+const nacl = require('tweetnacl');
+const fs = require('fs');
+
+function base64urlEncode(buf) {
+  return Buffer.from(buf)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '');
+}
+
+function base64urlDecode(str) {
+  const pad = str.length % 4 === 0 ? '' : '='.repeat(4 - (str.length % 4));
+  const b64 = (str + pad).replace(/-/g, '+').replace(/_/g, '/');
+  return Buffer.from(b64, 'base64');
+}
+
+function sha256Base64url(data) {
+  const digest = crypto.createHash('sha256').update(data).digest();
+  return base64urlEncode(digest);
+}
+
+function buildTranscript(input) {
+  return [
+    'TP1',
+    `tenant_id=${input.tenantId}`,
+    `api_id=${input.apiId}`,
+    `client_id=${input.clientId}`,
+    `method=${input.method}`,
+    `path=${input.path}`,
+    `body_hash=${input.bodyHash}`,
+    `time_bucket=${input.timeBucket}`,
+    `nonce=${input.nonce}`,
+  ].join('\n');
+}
+
+function randomNonce() {
+  return base64urlEncode(crypto.randomBytes(16));
+}
+
+function signProof({ tenantId, apiId, clientId, privateKey, method, path, body, bucketSeconds, timeBucketOverride, nonceOverride }) {
+ if (!tenantId || !apiId || !clientId) {
+   throw new Error('tenantId, apiId, and clientId are required');
+ }
+ if (!privateKey) {
+   throw new Error('privateKey is required');
+ }
+ if (!path) {
+   throw new Error('path is required');
+ }
+  const methodUpper = (method || 'GET').toUpperCase();
+  const bodyStr = body || '';
+  const bodyHash = `sha256:${sha256Base64url(Buffer.from(bodyStr))}`;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const bucket = bucketSeconds > 0 ? bucketSeconds : 20;
+  const timeBucket = Number.isFinite(timeBucketOverride) ? timeBucketOverride : Math.floor(nowSeconds / bucket);
+  const nonce = nonceOverride || randomNonce();
+
+  const transcript = buildTranscript({
+    tenantId,
+    apiId,
+    clientId,
+    method: methodUpper,
+    path,
+    bodyHash,
+    timeBucket,
+    nonce,
+  });
+
+  const digest = crypto.createHash('sha256').update(transcript).digest();
+  const priv = base64urlDecode(privateKey);
+  if (priv.length !== 64) {
+    throw new Error('privateKey must be ed25519 private key (64 bytes, base64url)');
+  }
+  const sig = nacl.sign.detached(digest, new Uint8Array(priv));
+  const signature = base64urlEncode(Buffer.from(sig));
+
+  const headers = {
+    'x-tp-tenant-id': tenantId,
+    'x-tp-api-id': apiId,
+    'x-tp-client-id': clientId,
+    'x-tp-time-bucket': String(timeBucket),
+    'x-tp-nonce': nonce,
+    'x-tp-signature': signature,
+    'x-tp-body-hash': bodyHash,
+  };
+
+  const verifyPayload = {
+    tenant_id: tenantId,
+    api_id: apiId,
+    client_id: clientId,
+    method: methodUpper,
+    path,
+    body_hash: bodyHash,
+    time_bucket: timeBucket,
+    nonce,
+    signature,
+  };
+
+  return {
+    headers,
+    verifyPayload,
+    transcript,
+    digest: base64urlEncode(digest),
+  };
+}
+
+async function sha256Base64urlAsync(data) {
+  if (!globalThis.crypto || !globalThis.crypto.subtle) {
+    throw new Error('WebCrypto is required for async hashing in browsers');
+  }
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', data);
+  return base64urlEncode(Buffer.from(digest));
+}
+
+async function signProofAsync({ tenantId, apiId, clientId, privateKey, method, path, body, bucketSeconds, timeBucketOverride, nonceOverride }) {
+  if (!tenantId || !apiId || !clientId) {
+    throw new Error('tenantId, apiId, and clientId are required');
+  }
+  if (!privateKey) {
+    throw new Error('privateKey is required');
+  }
+  if (!path) {
+    throw new Error('path is required');
+  }
+  const methodUpper = (method || 'GET').toUpperCase();
+  const bodyStr = body || '';
+  const bodyHash = `sha256:${await sha256Base64urlAsync(Buffer.from(bodyStr))}`;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const bucket = bucketSeconds > 0 ? bucketSeconds : 20;
+  const timeBucket = Number.isFinite(timeBucketOverride) ? timeBucketOverride : Math.floor(nowSeconds / bucket);
+  const nonce = nonceOverride || randomNonce();
+
+  const transcript = buildTranscript({
+    tenantId,
+    apiId,
+    clientId,
+    method: methodUpper,
+    path,
+    bodyHash,
+    timeBucket,
+    nonce,
+  });
+
+  const digest = crypto.createHash('sha256').update(transcript).digest();
+  const priv = base64urlDecode(privateKey);
+  if (priv.length !== 64) {
+    throw new Error('privateKey must be ed25519 private key (64 bytes, base64url)');
+  }
+  const sig = nacl.sign.detached(digest, new Uint8Array(priv));
+  const signature = base64urlEncode(Buffer.from(sig));
+
+  const headers = {
+    'x-tp-tenant-id': tenantId,
+    'x-tp-api-id': apiId,
+    'x-tp-client-id': clientId,
+    'x-tp-time-bucket': String(timeBucket),
+    'x-tp-nonce': nonce,
+    'x-tp-signature': signature,
+    'x-tp-body-hash': bodyHash,
+  };
+
+  const verifyPayload = {
+    tenant_id: tenantId,
+    api_id: apiId,
+    client_id: clientId,
+    method: methodUpper,
+    path,
+    body_hash: bodyHash,
+    time_bucket: timeBucket,
+    nonce,
+    signature,
+  };
+
+  return {
+    headers,
+    verifyPayload,
+    transcript,
+    digest: base64urlEncode(digest),
+  };
+}
+
+function fromFile(path) {
+  const raw = fs.readFileSync(path, 'utf8');
+  const cfg = JSON.parse(raw);
+  return createClient({
+    tenantId: cfg.tenant_id,
+    apiId: cfg.api_id,
+    clientId: cfg.client_id,
+    bucketSeconds: cfg.bucket_seconds,
+  });
+}
+
+function createClient({ tenantId, apiId, clientId, bucketSeconds }) {
+  return {
+    sign: ({ method, path, body, privateKey }) =>
+      signProof({ tenantId, apiId, clientId, privateKey, method, path, body, bucketSeconds }),
+    signAsync: ({ method, path, body, privateKey }) =>
+      signProofAsync({ tenantId, apiId, clientId, privateKey, method, path, body, bucketSeconds }),
+  };
+}
+
+module.exports = {
+  sign: signProof,
+  signAsync: signProofAsync,
+  createClient,
+  fromFile,
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "trustplane-sdk",
+  "version": "0.1.0",
+  "description": "Trustplane SDK (JS) for generating request proof headers",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "test_vector.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node test_vector.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "tweetnacl": "^1.0.3"
+  }
+}

package/test_vector.js

@@ -0,0 +1,19 @@
+const { sign } = require('./index');
+
+const out = sign({
+  tenantId: 'mergematter.io',
+  apiId: 'api_demo',
+  clientId: 'client_demo',
+  privateKey: 'dyIi-Xwr2tl6NdzkT0CXWUZkb9cPRXTSbDQgz-SCcORqDZPYyFAEXEGn6Eg6hlokBxvS8avUjpmk4VwaXmg7zQ',
+  method: 'GET',
+  path: '/orders',
+  body: '',
+  bucketSeconds: 20,
+  timeBucketOverride: 88498363,
+  nonceOverride: '9biCQnN2URhTCqhn_-orBQ'
+});
+
+console.log(out.headers);
+console.log(out.verifyPayload);
+console.log('transcript:', out.transcript);
+console.log('digest_b64url:', out.digest);