Backend Infrastructure Guide

// src/routes/signerId.ts  (Express / Hono / Fastify)
import { createHmac, randomBytes } from 'crypto';
import { db } from '../db';

const HMAC_SECRET = process.env.SIGNER_ID_HMAC_SECRET!; // 32+ random bytes

/**
 * Derive a deterministic opaque signer ID for a given user.
 * The HMAC ensures the same user always gets the same signer ID,
 * enabling idempotent re-enrollment without creating duplicate rows.
 */
function deriveSignerId(userId: string): string {
  const hmac = createHmac('sha256', HMAC_SECRET)
    .update(userId)
    .digest('hex')
    .slice(0, 16); // 64 bits of entropy — sufficient for uniqueness at scale
  return `ph_${hmac}@thephenom.app`;
}

export async function handleSignerIdRequest(req, res) {
  // userId is populated by your Cognito JWT middleware
  const { userId } = req.user;

  const signerId = deriveSignerId(userId);

  // Upsert — safe to call multiple times (e.g. after re-enrollment)
  await db.query(
    `INSERT INTO signer_identities (signer_id, user_id, created_at)
     VALUES ($1, $2, NOW())
     ON CONFLICT (signer_id) DO NOTHING`,
    [signerId, userId]
  );

  return res.json({ signerId });
}

// src/services/badge.ts
const BADGE_SIGNER_URL = 'https://badge.trusteddit.com/api/v1/sign';

export interface BadgeResult {
  badgeUrl: string;
  updatedManifest: string; // base64-encoded manifest with badge signature appended
  verificationUrl: string;
}

/**
 * Request a platform verification badge from the Trusteddit badge-signer.
 * Call this only after your platform has reviewed and approved the media.
 *
 * @param mediaId     - Your internal media ID
 * @param manifestBox - The device-signed C2PA manifest from the upload
 * @param mediaHash   - SHA-256 hash of the media file (hex)
 * @param apiKey      - Your Trusteddit platform API key (from dashboard)
 */
export async function requestBadge(
  mediaId: string,
  manifestBox: string,
  mediaHash: string,
  apiKey: string
): Promise<BadgeResult> {
  const response = await fetch(BADGE_SIGNER_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mediaId,
      manifestBox,
      mediaHash,
      platform: 'thephenom.app',
    }),
  });

  if (!response.ok) {
    const err = await response.json() as { code: string; message: string };
    throw new Error(`Badge signing failed [${err.code}]: ${err.message}`);
  }

  return response.json() as Promise<BadgeResult>;
}

// src/services/manifestStore.ts
const MANIFEST_STORE_URL = 'https://manifests.trusteddit.com/api/v1';

/**
 * Step 1 — Pre-register: Reserve a manifest slot before the media upload.
 * Returns a manifestId to include in the upload multipart form.
 */
export async function preRegisterManifest(
  signerId: string,
  mimeType: string,
  apiKey: string
): Promise<string> {
  const res = await fetch(`${MANIFEST_STORE_URL}/pre-register`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ signerId, mimeType }),
  });
  const { manifestId } = await res.json() as { manifestId: string };
  return manifestId;
}

/**
 * Step 2 — Sign: Attach the device-signed manifest box to the registered slot.
 */
export async function signManifest(
  manifestId: string,
  manifestBox: string,
  apiKey: string
): Promise<void> {
  await fetch(`${MANIFEST_STORE_URL}/${manifestId}/sign`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ manifestBox }),
  });
}

/**
 * Step 3 — Finalize: Attach the badge signature and mark the manifest complete.
 * After this call, the manifest is publicly resolvable by verifying applications.
 */
export async function finalizeManifest(
  manifestId: string,
  badgeManifest: string,
  apiKey: string
): Promise<string> {
  const res = await fetch(`${MANIFEST_STORE_URL}/${manifestId}/finalize`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ badgeManifest }),
  });
  const { verificationUrl } = await res.json() as { verificationUrl: string };
  return verificationUrl;
}

// Include in the C2PA claim (mobile, Step 3 / Step 5)
const claim = {
  // ...
  signature_info: {
    alg: 'ES256',
    cert: certPem,
    chain,
    // RFC 3161 TSA endpoint — Trusteddit issues RFC 3161 tokens
    tsa_url: 'https://tsa.trusteddit.com/rfc3161',
  },
};

// The C2PA SDK / @peculiar/x509 will call the TSA endpoint
// automatically when tsa_url is present in signature_info.
// The returned timestamp token is embedded in the manifest CMS structure.

// To verify a timestamp token independently:
// openssl ts -verify -in timestamp.tsr -data claim.json \
//   -CAfile trusteddit-tsa-root.pem

-- PostgreSQL schema

CREATE TABLE signer_identities (
  -- The opaque token used as certificate CN
  -- Format: ph_<16-char hex>@thephenom.app
  signer_id    TEXT        PRIMARY KEY,

  -- Your internal user ID (Cognito sub or DB primary key)
  user_id      TEXT        NOT NULL,

  -- UTC creation timestamp
  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),

  -- Tracks the currently active enrollment for this signer ID.
  -- A signer may re-enroll (e.g. after certificate expiry);
  -- only the most recent certificate serial is stored here.
  cert_serial  TEXT,
  cert_expires TIMESTAMPTZ,

  -- Optional: last known device platform for auditing
  platform     TEXT
);

-- Index for reverse-lookup: given a user_id, find their signer_id(s)
CREATE INDEX idx_signer_identities_user_id ON signer_identities (user_id);

-- Row-level security: only the API role may read this table
ALTER TABLE signer_identities ENABLE ROW LEVEL SECURITY;

CREATE POLICY api_only ON signer_identities
  USING (current_user = 'api_service_role');