{"_id":"@capglyph/sdk","name":"@capglyph/sdk","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.2":{"name":"@capglyph/sdk","version":"0.1.2","description":"CapGlyph TypeScript SDK — Local (WASM) + API (capglyphd) with conformance vectors","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","build:wasm":"echo 'TODO: wasm-pack build --target web --out-dir wasm from ../capglyph-core (see wasm/README.md)'","test":"vitest run","test:conformance":"vitest run tests/conformance.test.ts","lint":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["capglyph","watermark","stego","credential","wasm","cbor","hmac"],"author":{"name":"CapGlyph Authors"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/CapGlyph/capglyph-sdk-js.git"},"engines":{"node":">=18"},"devDependencies":{"@types/node":"^26.4.0","typescript":"^5.6.0","vitest":"^2.1.0"},"_id":"@capglyph/sdk@0.1.2","gitHead":"d46f4256ef73e8319805903b8f8670f8f872bc35","bugs":{"url":"https://github.com/CapGlyph/capglyph-sdk-js/issues"},"homepage":"https://github.com/CapGlyph/capglyph-sdk-js#readme","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-enOzBbARMn2q2EqRfniQTI1NIB8W+YKhpecKL3ucDWWL3IGuoMNjafKCHmS4MDMoFLfltSJxzgRx4V5XUQUzEQ==","shasum":"0e07bf455ef111dee83a3d395a03f30b999a9dc6","tarball":"https://registry.npmjs.org/@capglyph/sdk/-/sdk-0.1.2.tgz","fileCount":25,"unpackedSize":105585,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDqeZslVkZDKoe5fcuzrKm/NEQGCnbagcvB9uRaXTp8jwIhANsdH2GrkjMwieUnEOkyJ1QIztN7ZiLczMI+6GkXTyAJ"}]},"_npmUser":{"name":"xuepoo","email":"xuepoofoter@gmail.com"},"directories":{},"maintainers":[{"name":"xuepoo","email":"xuepoofoter@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.2_1788281668896_0.15736177775477578"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-01T16:54:28.700Z","0.1.2":"2026-09-01T16:54:29.036Z","modified":"2026-09-01T16:54:29.268Z"},"maintainers":[{"name":"xuepoo","email":"xuepoofoter@gmail.com"}],"description":"CapGlyph TypeScript SDK — Local (WASM) + API (capglyphd) with conformance vectors","homepage":"https://github.com/CapGlyph/capglyph-sdk-js#readme","keywords":["capglyph","watermark","stego","credential","wasm","cbor","hmac"],"repository":{"type":"git","url":"git+https://github.com/CapGlyph/capglyph-sdk-js.git"},"author":{"name":"CapGlyph Authors"},"bugs":{"url":"https://github.com/CapGlyph/capglyph-sdk-js/issues"},"license":"Apache-2.0","readme":"# @capglyph/sdk — TypeScript SDK for CapGlyph\n\nTypeScript (Browser / Node / Cloudflare Workers) SDK for **CapGlyph** — image-native credential + stego payload infrastructure.\n\n- Spec: [`CapGlyph/capglyph-spec` v1.0.0](https://github.com/CapGlyph/capglyph-spec) · Core: [`CapGlyph/capglyph-core` v0.1.0](https://github.com/CapGlyph/capglyph-core)\n- Conformance: [`CapGlyph/capglyph-test-vectors` 1024/1024](https://github.com/CapGlyph/capglyph-test-vectors) — `vectors/{valid,invalid,malformed,tampered,expired,revoked}`\n\n## Two-type design\n\n| SDK type      | Transport                   | Implementation                                                                | Use case                                                                                                        |\n| ------------- | --------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| **Local SDK** | WASM/FFI from Rust Core     | `src/local.ts` → `wasm/pkg/capglyph_core` (fallback `src/framing.ts` pure JS) | Browser/Workers `embed`/`verify` without server, offline seal/open                                              |\n| **API SDK**   | Typed HTTP client (OpenAPI) | `src/client.ts` `CapglyphClient` (`fetch`)                                    | Node/edge calling `capglyphd` (`/v1/seal`, `/v1/open`, `/v1/embed`, `/v1/verify`, `/v1/extract`, `/v1/consume`) |\n\n> Mirrors the SDK roadmap in `capglyph-spec/docs` and `capglyph-docs`: Local for credential-at-edge, API for centralized policy/consume/revoke.\n\n## Install\n\n```bash\nnpm install @capglyph/sdk\n# or pin to dist-tag\nnpm install @capglyph/sdk@0.1.0\n```\n\nRequires Node 18+ (native `fetch`, `crypto`).\n\n## Quickstart\n\n### Local (WASM or JS fallback) — seal/open without server\n\n```ts\nimport { LocalClient } from \"@capglyph/sdk\";\n\nconst kMac = Uint8Array.from(Buffer.from(\"42\".repeat(32), \"hex\")); // HKDF-derived K_mac (capglyph_core::keying)\nconst payload = new TextEncoder().encode(\"credential-128b-token-....\");\n\nconst local = new LocalClient();\nawait local.init(); // loads wasm/pkg/capglyph_core.js when built; otherwise JS fallback\n\nconst sealed = local.seal(payload, kMac); // Uint8Array: CBOR frame || HMAC-SHA256\nconst { header, payload: out } = local.open(sealed, kMac);\nconsole.log(header); // { version: 1, payloadType: \"Credential\", flags: 0, payloadLen: 16 }\nconsole.log(new TextDecoder().decode(out));\n```\n\nWASM build (optional — JS fallback is byte-identical for framing):\n\n```bash\n# from isolated monorepo /mnt/data/Workspace/Projects/capglyph\nwasm-pack build --target web ../capglyph-core --out-dir ../capglyph-sdk-js/wasm/pkg\n# re-run tests with WASM\nnpm test\n```\n\nSee `wasm/README.md` for bundler vs web targets and Cloudflare Workers wiring.\n\n### API (capglyphd) — typed client\n\n```ts\nimport { CapglyphClient } from \"@capglyph/sdk\";\n\nconst client = new CapglyphClient({\n  baseUrl: \"https://capglyph.example.com\",\n  apiKey: process.env.CAPGLYPH_API_KEY,\n});\n\n// Seal via server (mirrors capglyph_core::framing::seal)\nconst { sealed_hex } = await client.seal({\n  payload_hex: \"001122...\",\n  k_mac_hex: \"42\".repeat(32),\n  payload_type: 1,\n});\nconst { payload_hex } = await client.open({\n  sealed_hex,\n  k_mac_hex: \"42\".repeat(32),\n});\n\n// Image carrier (DCT/DWT via capglyphd)\nconst pngBase64 = await readFile(\"cover.png\", \"base64\");\nconst { image_base64 } = await client.embedImage({\n  image_base64: pngBase64,\n  mode: \"dwt\",\n  payload_hex: \"deadbeef\",\n  k_mac_hex: \"...\",\n});\nconst { present } = await client.verifyImage({ image_base64, mode: \"dwt\" });\n```\n\nError handling is fail-closed with `E_*` codes (spec §8):\n\n```ts\nimport { CapglyphApiError } from \"@capglyph/sdk\";\ntry {\n  await client.open({ sealed_hex: tamperedHex, k_mac_hex: kMacHex });\n} catch (e) {\n  if (e instanceof CapglyphApiError) console.error(e.code); // E_AUTH_FAILED, E_EXPIRED, ...\n}\n```\n\n## Conformance\n\nVectors: `CapGlyph/capglyph-test-vectors` `1024` fixtures (`valid 256 / invalid 128 / malformed 128 / tampered 256 / expired 128 / revoked 128`). SDK must pass `valid` and fail others with the documented `E_*`.\n\n```bash\n# via Vitest (JS fallback, no WASM needed)\nnpm test\n\n# verbose\nnpm run test:conformance\n\n# standalone harness (no cargo)\nnode --loader ts-node/esm src/conformance.ts  # or vitest\npython3 ../capglyph-test-vectors/tools/conformance.py --vectors ../capglyph-test-vectors/vectors\n```\n\nExpected:\n\n```\nvalid     256/256 pass ✓\ninvalid   128/128 pass ✓\nmalformed 128/128 pass ✓\ntampered  256/256 pass ✓\nexpired   128/128 pass ✓\nrevoked   128/128 pass ✓\ntotal    1024/1024 vectors passed — conformance ✓\n```\n\nVectors are resolved via `CAPGLYPH_VECTORS` or sibling `../capglyph-test-vectors/vectors` (isolated monorepo) or `/mnt/data/Workspace/Projects/capglyph/capglyph-test-vectors/vectors`.\n\n## API Reference\n\n### `src/framing.ts` (Local pure-JS, mirrors `capglyph_core::framing`)\n\n- `seal(payload, params, kMac) → Uint8Array` — `CBOR([version, type, flags, len, payload]) || HMAC-SHA256`\n- `open(sealed, kMac) → { header, payload }` — verify then CBOR decode, throws classified `E_*`\n- `cborEncode / cborDecode / cborValidate`, `hmacTag / hmacVerify`, `classifyError`, `hexToBytes / bytesToHex`\n\n### `src/local.ts`\n\n- `LocalClient` — `seal`, `sealHex`, `open`, `openHex`, `validate`, `usingWasm`, `embedImage` (TODO until carrier WASM), `verifyImage`\n- `local` singleton\n\n### `src/client.ts`\n\n- `CapglyphClient({ baseUrl, apiKey?, fetch? })` — `seal`, `open`, `validate`, `embedImage`, `verifyImage`, `extractImage`, `consume`, `revoke`, `info`, `health`\n- `CapglyphApiError { code, status, message }`, `clientFromEnv()`\n\n### `src/conformance.ts`\n\n- `validateVector(vec)`, `validateVectors(vectors)`, `findVectorsRoot()`, `loadVectors(root)`\n\n## Cloudflare Workers\n\n```ts\nimport { LocalClient } from \"@capglyph/sdk\";\nexport default {\n  async fetch(req: Request) {\n    const local = new LocalClient();\n    // Workers: pre-bundle wasm/pkg/capglyph_core_bg.wasm via wrangler --assets, or use JS fallback (no WASM needed for framing)\n    const kMac = Uint8Array.from(atob(env.K_MAC_B64), (c) => c.charCodeAt(0));\n    const sealed = local.seal(new TextEncoder().encode(\"hello\"), kMac);\n    return new Response(sealed);\n  },\n};\n```\n\n## Building\n\n```bash\nnpm install\nnpm run build   # tsc → dist/\nnpm test        # vitest run (1024/1024)\n```\n\n## License\n\nApache-2.0 — same as `CapGlyph/capglyph-core`.\n","readmeFilename":"README.md","_rev":"1-4276d6160fa30083e380fd70a9c3cb4e"}