@tegis/player 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to `@tegis/player` are documented here. This project follows [semver](https://semver.org).
+
+## [0.1.0] — unreleased
+
+Initial extraction from the Tegis reference SDK (formerly the private `@aegis/sdk`).
+
+- `TegisPlayer` — the browser hot path (attest → handshake → mint → renew) with WebCrypto AES-CTR
+  segment decryption over MSE.
+- `loadWasmHandshake` / `loadWhitenedHandshake` — WASM-backed handshake (obfuscation-grade), byte-identical
+  to the WebCrypto path so the Go mint accepts it unchanged. Ships the compiled `wasm/hmac-sha256.wasm`.
+- Self-contained: no repo-relative imports.
+
+> Note: demo-only `x-aegis-*` request headers are retained as the current frozen wire contract; a real
+> deployment routes by Host and never sets them. Renaming the wire headers is a coordinated server+client
+> change, tracked separately from this packaging work.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Burak Saraloglu (okbrk)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @tegis/player
+
+Browser player SDK for **Tegis** — the content-protection gateway for video. It runs the protected hot
+path in the browser: **attest → handshake → mint → renew**, then decrypts and plays segments with
+WebCrypto (AES-CTR) over Media Source Extensions. The player **never holds a tenant key** — only a
+short-lived attestation and playback grant.
+
+The crypto/fetch/decrypt core runs identically in the browser and in Bun (for headless e2e); the MSE
+glue is browser-only and guarded.
+
+## Install
+
+```sh
+bun add @tegis/player
+```
+
+## Usage
+
+```ts
+import { TegisPlayer, loadWasmHandshake } from "@tegis/player";
+
+// 1. (Recommended) load the WASM handshake so the per-session signature is computed inside an opaque
+//    module rather than a one-line JS HMAC. `handshakeSecret` is delivered by Tegis (WASM-whitened in prod).
+const wasm = await fetch(new URL("@tegis/player/wasm/hmac-sha256.wasm", import.meta.url)).then(r => r.arrayBuffer());
+const handshakeFn = await loadWasmHandshake(handshakeSecret, wasm);
+
+const player = new TegisPlayer({
+  mint: "https://your-tenant.tegis.io",   // your tenant CNAME (mint endpoint)
+  edge: "https://your-tenant.tegis.io",   // edge / CDN base
+  tid: "t_yourtenant",
+  handshakeSecret,                         // Uint8Array, delivered by Tegis
+  handshakeFn,                             // optional WASM override (falls back to WebCrypto)
+});
+
+// `entitlement` comes from your backend via @tegis/server.
+const video = document.querySelector("video")!;
+await player.play(video, { assetId, entitlement });
+```
+
+For best join-time, call `player.prewarm()` at page load (solves the bot-wall off the click→play path).
+
+## API
+
+- `new TegisPlayer(config: BrowserPlayerConfig)`
+- `.prewarm(opts?)` — pre-solve attestation and hold it
+- `.play(video, { assetId, entitlement, ... })` — full hot path + MSE playback
+- `.mint(...)`, `.renew(...)`, `.decryptedSegment(...)` — lower-level steps
+- `loadWasmHandshake(secret, wasmBytes)` / `loadWhitenedHandshake(wasmBytes)` — build a `HandshakeFn`
+
+A `@tegis/player/bundle` entry exposes `TegisPlayer` on `globalThis` for `<script>`-tag use.
+
+## Browser support
+
+Playback requires **real Chrome** (H.264 + MSE) — see the Tegis docs for the supported-browser matrix.
+Surface a clear unsupported-browser message to viewers on other engines.
+
+MIT © okbrk

package/dist/bundle-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bundle-entry.js

@@ -0,0 +1,188 @@
+// src/crypto.ts
+var te = new TextEncoder;
+function b64u(buf) {
+  const b = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  let s = "";
+  for (const x of b)
+    s += String.fromCharCode(x);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unb64u(s) {
+  s = s.replace(/-/g, "+").replace(/_/g, "/");
+  while (s.length % 4)
+    s += "=";
+  const bin = atob(s);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0;i < bin.length; i++)
+    out[i] = bin.charCodeAt(i);
+  return out;
+}
+async function hmacSha256(secret, msg) {
+  const key = await crypto.subtle.importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return new Uint8Array(await crypto.subtle.sign("HMAC", key, te.encode(msg)));
+}
+async function sha256b64u(s) {
+  return b64u(await crypto.subtle.digest("SHA-256", te.encode(s)));
+}
+async function handshake(secret, att, ent, nonce, t) {
+  const d = await sha256b64u(ent);
+  return b64u(await hmacSha256(secret, `${att}.${d}.${nonce}.${t}`));
+}
+async function hbSign(hbKeyB64u, hbJSON) {
+  return b64u(await hmacSha256(unb64u(hbKeyB64u), hbJSON));
+}
+async function decryptSegment(keyRaw, blob) {
+  const iv = blob.slice(0, 16);
+  const ct = blob.slice(16);
+  const key = await crypto.subtle.importKey("raw", keyRaw, { name: "AES-CTR" }, false, ["decrypt"]);
+  const pt = await crypto.subtle.decrypt({ name: "AES-CTR", counter: iv, length: 128 }, key, ct);
+  return new Uint8Array(pt);
+}
+
+// src/player.ts
+function randHex(n) {
+  const b = new Uint8Array(n);
+  crypto.getRandomValues(b);
+  return [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+}
+
+class TegisPlayer {
+  cfg;
+  att;
+  attSes;
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  get f() {
+    return this.cfg.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  }
+  hdr(extra = {}) {
+    const h = { "content-type": "application/json", ...extra };
+    if (this.cfg.demoHeaders) {
+      h["x-aegis-tenant"] = this.cfg.tid;
+      if (this.cfg.clientIp)
+        h["x-aegis-client-ip"] = this.cfg.clientIp;
+    }
+    return h;
+  }
+  async post(path, body) {
+    const r = await this.f(this.cfg.mint + path, { method: "POST", headers: this.hdr(), body: JSON.stringify(body) });
+    return { status: r.status, json: await r.json().catch(() => ({})) };
+  }
+  handshake(att, ent, nonce, t) {
+    return (this.cfg.handshakeFn ?? ((a, e, n, tt) => handshake(this.cfg.handshakeSecret, a, e, n, tt)))(att, ent, nonce, t);
+  }
+  async prewarm(opts = {}) {
+    const ses = opts.ses ?? "ses_" + randHex(4);
+    const body = { ses, fph: opts.fph ?? "fp_" + ses };
+    if (opts.solution) {
+      body.nonce = opts.nonce;
+      body.solution = opts.solution;
+    }
+    if (opts.token)
+      body.token = opts.token;
+    const r = await this.post("/attest/v1/verify", body);
+    if (!r.json.att)
+      throw new Error("attestation failed: " + JSON.stringify(r.json));
+    this.att = r.json.att;
+    this.attSes = ses;
+    return this.att;
+  }
+  async mint(opts) {
+    const ses = this.attSes ?? opts.ses ?? "ses_" + randHex(4);
+    if (!this.att)
+      await this.prewarm({ ses, fph: opts.fph, token: opts.token });
+    const nonce = (await this.post("/mint/v1/nonce", { ses })).json.nonce;
+    const t = Math.floor(Date.now() / 1000);
+    const hs = await this.handshake(this.att, opts.entitlement, nonce, t);
+    const r = await this.post("/mint/v1", { assetId: opts.assetId, att: this.att, entitlement: opts.entitlement, nonce, handshake: hs, t });
+    if (r.status !== 200)
+      throw new Error("mint failed: " + r.status + " " + JSON.stringify(r.json));
+    return r.json;
+  }
+  async contentKey(assetId) {
+    const r = await this.f(`${this.cfg.mint}/key/v1/${assetId}?att=${this.att}`, { headers: this.hdr() });
+    if (r.status !== 200)
+      throw new Error("key fetch failed: " + r.status);
+    return unb64u((await r.json()).key);
+  }
+  async fetchBytes(url) {
+    const r = await this.f(url.startsWith("http") ? url : this.cfg.edge + url, { headers: this.hdr() });
+    if (r.status !== 200)
+      throw new Error("fetch failed " + r.status + ": " + url);
+    return new Uint8Array(await r.arrayBuffer());
+  }
+  async decryptedSegment(assetId, url, key) {
+    const k = key ?? await this.contentKey(assetId);
+    return decryptSegment(k, await this.fetchBytes(url));
+  }
+  async renew(playbackId, hbKeyB64u, progress) {
+    const hb = { pbk: playbackId, pos: progress.pos, seq: progress.seq, state: "playing", iat: Math.floor(Date.now() / 1000) };
+    const sig = await hbSign(hbKeyB64u, JSON.stringify(hb));
+    const r = await this.post("/mint/v1/renew", { playbackId, heartbeat: hb, sig });
+    if (r.status !== 200)
+      throw new Error("renew failed: " + r.status);
+    return r.json;
+  }
+  async play(video, opts) {
+    if (typeof MediaSource === "undefined")
+      throw new Error("MSE unavailable in this environment");
+    const g = await this.mint(opts);
+    const key = await this.contentKey(opts.assetId);
+    const ms = new MediaSource;
+    video.src = URL.createObjectURL(ms);
+    await new Promise((res) => ms.addEventListener("sourceopen", () => res(), { once: true }));
+    const mime = opts.mime ?? 'video/mp4; codecs="avc1.4d401e, mp4a.40.2"';
+    const sb = ms.addSourceBuffer(mime);
+    const append = (buf) => new Promise((res, rej) => {
+      sb.addEventListener("updateend", () => res(), { once: true });
+      sb.addEventListener("error", (e) => rej(e), { once: true });
+      sb.appendBuffer(buf);
+    });
+    await append(await this.fetchBytes(g.init));
+    for (const url of g.manifest) {
+      let seg;
+      try {
+        seg = await this.decryptedSegment(opts.assetId, url, key);
+      } catch {
+        break;
+      }
+      await append(seg);
+    }
+    ms.endOfStream();
+    await video.play().catch(() => {});
+    return g;
+  }
+}
+
+// src/handshake-wasm.ts
+async function loadWhitenedHandshake(wasmBytes) {
+  const { instance } = await WebAssembly.instantiate(wasmBytes, {
+    env: { abort: () => {
+      throw new Error("wasm abort");
+    } }
+  });
+  const ex = instance.exports;
+  const te2 = new TextEncoder;
+  const mem = () => new Uint8Array(ex.memory.buffer);
+  function write(data) {
+    const p = ex.alloc(data.length);
+    mem().set(data, p);
+    return p;
+  }
+  function call(fn, data) {
+    const p = write(data);
+    const out = ex.alloc(32);
+    fn(p, data.length, out);
+    return mem().slice(out, out + 32);
+  }
+  return async (att, ent, nonce, t) => {
+    const entDigest = b64u(call(ex.sha256, te2.encode(ent)));
+    const msg = te2.encode(`${att}.${entDigest}.${nonce}.${t}`);
+    return b64u(call(ex.signKeyed, msg));
+  };
+}
+
+// src/bundle-entry.ts
+globalThis.TegisPlayer = TegisPlayer;
+globalThis.TegisLoadWhitenedHandshake = loadWhitenedHandshake;

package/dist/crypto.d.ts

@@ -0,0 +1,17 @@
+export declare function b64u(buf: ArrayBuffer | Uint8Array): string;
+export declare function unb64u(s: string): Uint8Array;
+export declare function sha256b64u(s: string): Promise<string>;
+/**
+ * The per-session handshake — HMAC(secret, `att.sha256(ent)b64u.nonce.t`) — identical to the Go mint's
+ * verifyHandshake. In production this runs inside the WASM module (F1 §8, obfuscation-grade); this
+ * WebCrypto path is the reference/fallback and proves byte-parity with the mint.
+ */
+export declare function handshake(secret: Uint8Array, att: string, ent: string, nonce: string, t: number): Promise<string>;
+/** Heartbeat signature for the renewal loop — HMAC(hbKey, canonical-heartbeat-json). */
+export declare function hbSign(hbKeyB64u: string, hbJSON: string): Promise<string>;
+/**
+ * Decrypt a reference segment: blob = IV(16) ‖ AES-128-CTR(key, plaintext). Returns the plaintext fMP4.
+ * (F7 will add an EME clear-key path for ISO-CENC; this manual path is the launch decrypt for the
+ * whole-segment-CTR packaging the reference produces today.)
+ */
+export declare function decryptSegment(keyRaw: Uint8Array, blob: Uint8Array): Promise<Uint8Array>;

package/dist/handshake-wasm.d.ts

@@ -0,0 +1,13 @@
+export type HandshakeFn = (att: string, ent: string, nonce: string, t: number) => Promise<string>;
+/**
+ * Build a WASM-backed handshake function bound to the tenant's handshake secret. `wasmBytes` is the
+ * compiled hmac-sha256.wasm (embedded in the bundle, or fetched).
+ */
+export declare function loadWasmHandshake(secret: Uint8Array, wasmBytes: BufferSource): Promise<HandshakeFn>;
+/**
+ * F9: load a per-tenant WHITENED module (src/whiten.ts output). Unlike loadWasmHandshake, it takes NO
+ * secret — the tenant's HMAC key lives inside the module as split ipad/opad midstates and never crosses
+ * the JS↔WASM boundary. The module exports `sha256` (pure, for the entitlement digest) and `signKeyed`
+ * (HMAC with the baked key). Output is byte-identical to HMAC-SHA256(hs_tenant, msg), so the mint accepts it.
+ */
+export declare function loadWhitenedHandshake(wasmBytes: BufferSource): Promise<HandshakeFn>;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { TegisPlayer } from "./player.js";
+export type { BrowserPlayerConfig, Grant } from "./player.js";
+export { loadWasmHandshake, loadWhitenedHandshake } from "./handshake-wasm.js";
+export type { HandshakeFn } from "./handshake-wasm.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export {
+  loadWhitenedHandshake,
+  loadWasmHandshake,
+  TegisPlayer
+};

package/dist/player.d.ts

@@ -0,0 +1,76 @@
+export interface BrowserPlayerConfig {
+    mint: string;
+    edge: string;
+    tid: string;
+    handshakeSecret: Uint8Array;
+    handshakeFn?: (att: string, ent: string, nonce: string, t: number) => Promise<string>;
+    demoHeaders?: boolean;
+    clientIp?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface Grant {
+    grant: string;
+    playbackId: string;
+    hbKeyB64u: string;
+    init: string;
+    manifest: string[];
+    window: {
+        from: number;
+        to: number;
+    };
+    res: string;
+}
+export declare class TegisPlayer {
+    private cfg;
+    private att?;
+    private attSes?;
+    constructor(cfg: BrowserPlayerConfig);
+    private get f();
+    private hdr;
+    private post;
+    private handshake;
+    /** Pre-warm attestation OFF the click→play path (F1 §3): solve the bot-wall at page load, hold the att. */
+    prewarm(opts?: {
+        ses?: string;
+        fph?: string;
+        nonce?: string;
+        solution?: string;
+        token?: string;
+    }): Promise<string>;
+    /** Mint a playback grant for an asset (pre-warms inline if not already warm). */
+    mint(opts: {
+        assetId: string;
+        entitlement: string;
+        ses?: string;
+        fph?: string;
+        token?: string;
+    }): Promise<Grant>;
+    /** Fetch the att-gated content key (AES-128, 16 bytes). */
+    contentKey(assetId: string): Promise<Uint8Array>;
+    fetchBytes(url: string): Promise<Uint8Array>;
+    /** The headless-verifiable core: fetch a media segment from the edge/CDN + decrypt it with WebCrypto. */
+    decryptedSegment(assetId: string, url: string, key?: Uint8Array): Promise<Uint8Array>;
+    /** Steady-state renewal: report realtime progress to receive the next signed window. */
+    renew(playbackId: string, hbKeyB64u: string, progress: {
+        pos: number;
+        seq: number;
+    }): Promise<{
+        manifest: string[];
+        window: {
+            from: number;
+            to: number;
+        };
+    }>;
+    /**
+     * Full browser playback via MSE (browser-only): mint → append the init segment → fetch+decrypt+append
+     * each media segment → play. The att-gated key is fetched once. Returns the grant.
+     */
+    play(video: HTMLVideoElement, opts: {
+        assetId: string;
+        entitlement: string;
+        ses?: string;
+        fph?: string;
+        mime?: string;
+        token?: string;
+    }): Promise<Grant>;
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@tegis/player",
+  "version": "0.1.0",
+  "description": "Tegis browser player SDK — attest → WASM handshake → mint → renew, with WebCrypto AES-CTR segment playback. Never holds a tenant key.",
+  "type": "module",
+  "license": "MIT",
+  "author": "okbrk <burak@okbrk.com>",
+  "homepage": "https://tegis.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/okbrk/aegis.git",
+    "directory": "reference/sdk-ts/packages/player"
+  },
+  "keywords": [
+    "tegis",
+    "content-protection",
+    "anti-piracy",
+    "player",
+    "video",
+    "drm",
+    "mse",
+    "webcrypto",
+    "wasm",
+    "hls"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./bundle": {
+      "types": "./dist/bundle-entry.d.ts",
+      "default": "./dist/bundle-entry.js"
+    },
+    "./wasm/hmac-sha256.wasm": "./wasm/hmac-sha256.wasm",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "browser": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "wasm/hmac-sha256.wasm",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./src/bundle-entry.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "build": "bun run clean && bun build ./src/index.ts ./src/bundle-entry.ts --target=browser --format=esm --outdir dist && tsc -p tsconfig.build.json && bun ../../scripts/fix-dts.ts dist",
+    "prepublishOnly": "bun run build"
+  }
+}