sello 0.1.0 → 0.1.2

package/dist/receipt/body.js

@@ -0,0 +1,210 @@
+import {
+               
+                  
+  cborTag,
+  decodeCbor,
+  encodeCbor,
+} from "../cbor.js";
+import { assertAgentIdentifier } from "../crypto/identifiers.js";
+
+                                                          
+
+                           
+                             
+                        
+                                  
+                                   
+                                
+                    
+                                     
+  
+
+export const ZERO_SHA256_DIGEST = new Uint8Array(32);
+
+const RESULT_STATUSES = new Set              (["success", "error", "denied"]);
+const RECEIPT_KEYS = new Set([
+  "agent-identifier",
+  "action-type",
+  "action-input-hash",
+  "action-output-hash",
+  "result-status",
+  "timestamp",
+  "service-defined-fields",
+]);
+
+export function encodeReceiptBody(receipt             )             {
+  validateReceiptBody(receipt);
+
+  const map          = new Map([
+    ["agent-identifier", receipt["agent-identifier"]],
+    ["action-type", receipt["action-type"]],
+    ["action-input-hash", receipt["action-input-hash"]],
+    ["action-output-hash", receipt["action-output-hash"]],
+    ["result-status", receipt["result-status"]],
+    ["timestamp", cborTag(0, receipt.timestamp)],
+  ]);
+
+  if (receipt["service-defined-fields"]) {
+    map.set("service-defined-fields", receipt["service-defined-fields"]);
+  }
+
+  return encodeCbor(map);
+}
+
+export function decodeReceiptBody(bytes            )              {
+  const value = decodeCbor(bytes);
+
+  if (!(value instanceof Map)) {
+    throw new TypeError("receipt body must be a CBOR map");
+  }
+
+  for (const key of value.keys()) {
+    if (typeof key !== "string" || !RECEIPT_KEYS.has(key)) {
+      throw new TypeError(`receipt body contains unknown field ${String(key)}`);
+    }
+  }
+
+  const timestamp = value.get("timestamp");
+  const receipt              = {
+    "agent-identifier": expectString(value, "agent-identifier"),
+    "action-type": expectString(value, "action-type"),
+    "action-input-hash": expectBytes(value, "action-input-hash"),
+    "action-output-hash": expectBytes(value, "action-output-hash"),
+    "result-status": expectResultStatus(value, "result-status"),
+    timestamp: expectTag0Timestamp(timestamp),
+  };
+
+  if (value.has("service-defined-fields")) {
+    const serviceFields = value.get("service-defined-fields");
+    if (!(serviceFields instanceof Map)) {
+      throw new TypeError("service-defined-fields must be a CBOR map");
+    }
+    assertServiceDefinedFields(serviceFields);
+    receipt["service-defined-fields"] = serviceFields;
+  }
+
+  validateReceiptBody(receipt);
+  return receipt;
+}
+
+export function validateReceiptBody(receipt             )       {
+  assertObject(receipt, "receipt");
+  assertAgentIdentifier(receipt["agent-identifier"], "agent-identifier");
+  assertString(receipt["action-type"], "action-type");
+  assertSha256Digest(receipt["action-input-hash"], "action-input-hash");
+  assertSha256Digest(receipt["action-output-hash"], "action-output-hash");
+  assertResultStatus(receipt["result-status"], "result-status");
+  assertUtcTimestamp(receipt.timestamp, "timestamp");
+
+  if (
+    receipt["result-status"] === "denied" &&
+    !bytesEqual(receipt["action-output-hash"], ZERO_SHA256_DIGEST)
+  ) {
+    throw new TypeError("denied receipts must use all-zero action-output-hash");
+  }
+
+  if (receipt["service-defined-fields"] !== undefined) {
+    if (!(receipt["service-defined-fields"] instanceof Map)) {
+      throw new TypeError("service-defined-fields must be a Map");
+    }
+    assertServiceDefinedFields(receipt["service-defined-fields"]);
+  }
+}
+
+function expectString(map         , key        )         {
+  const value = map.get(key);
+  assertString(value, key);
+  return value;
+}
+
+function expectBytes(map         , key        )             {
+  const value = map.get(key);
+  assertSha256Digest(value, key);
+  return value;
+}
+
+function expectResultStatus(map         , key        )               {
+  const value = map.get(key);
+  assertResultStatus(value, key);
+  return value;
+}
+
+function expectTag0Timestamp(value         )         {
+  if (!isTagged(value) || value.tag !== 0 || typeof value.value !== "string") {
+    throw new TypeError("timestamp must be CBOR tag 0 containing a string");
+  }
+
+  assertUtcTimestamp(value.value, "timestamp");
+  return value.value;
+}
+
+function assertObject(value         , name        )                          {
+  if (typeof value !== "object" || value === null) {
+    throw new TypeError(`${name} must be an object`);
+  }
+}
+
+function assertString(value         , name        )                          {
+  if (typeof value !== "string") {
+    throw new TypeError(`${name} must be a string`);
+  }
+}
+
+function assertSha256Digest(value         , name        )                              {
+  if (!(value instanceof Uint8Array) || value.byteLength !== 32) {
+    throw new TypeError(`${name} must be a 32-byte SHA-256 digest`);
+  }
+}
+
+function assertResultStatus(value         , name        )                                {
+  if (typeof value !== "string" || !RESULT_STATUSES.has(value                )) {
+    throw new TypeError(`${name} must be success, error, or denied`);
+  }
+}
+
+function assertUtcTimestamp(value         , name        )                          {
+  assertString(value, name);
+
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(value)) {
+    throw new TypeError(`${name} must be an RFC 3339 UTC timestamp`);
+  }
+
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed)) {
+    throw new TypeError(`${name} must be a valid timestamp`);
+  }
+}
+
+function assertServiceDefinedFields(value         )       {
+  for (const [key, entryValue] of value.entries()) {
+    if (typeof key !== "string") {
+      throw new TypeError("service-defined-fields keys must be service identifiers");
+    }
+    if (!(entryValue instanceof Map)) {
+      throw new TypeError("service-defined-fields values must be CBOR maps");
+    }
+  }
+}
+
+function isTagged(value         )                      {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "tag" in value &&
+    "value" in value
+  );
+}
+
+function bytesEqual(a            , b            )          {
+  if (a.byteLength !== b.byteLength) {
+    return false;
+  }
+
+  for (let index = 0; index < a.byteLength; index += 1) {
+    if (a[index] !== b[index]) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/dist/registry/json-registry.js

@@ -0,0 +1,233 @@
+import {
+  assertEd25519PublicKey,
+  assertEd25519Signature,
+  signEd25519,
+  verifyEd25519Signature,
+} from "../crypto/ed25519.js";
+import { toHex } from "../crypto/identifiers.js";
+
+                             
+                 
+                            
+                               
+  
+
+                               
+                 
+                    
+  
+
+                                    
+                                      
+                                        
+  
+
+                                       
+                            
+                             
+                                 
+  
+
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+const BASE64URL_32_BYTE_LENGTH = 43;
+
+export function signRegistryJson(
+  registryBytes            ,
+  trustRootPrivateKey            ,
+)         {
+  assertBytes(registryBytes, "registryBytes");
+  return base64urlEncode(signEd25519(registryBytes, trustRootPrivateKey));
+}
+
+export function loadSignedRegistry(
+  input                         ,
+)                       {
+  verifyRegistrySignature(
+    input.registryBytes,
+    input.signatureBase64Url,
+    input.trustRootPublicKey,
+  );
+
+  return parseRegistry(input.registryBytes);
+}
+
+export function verifyRegistrySignature(
+  registryBytes            ,
+  signatureBase64Url        ,
+  trustRootPublicKey            ,
+)       {
+  assertBytes(registryBytes, "registryBytes");
+  assertEd25519PublicKey(trustRootPublicKey, "trustRootPublicKey");
+  const signature = base64urlDecode(signatureBase64Url, "registry signature");
+  assertEd25519Signature(signature, "registry signature");
+
+  if (!verifyEd25519Signature(registryBytes, signature, trustRootPublicKey)) {
+    throw new TypeError("registry signature verification failed");
+  }
+}
+
+export function parseRegistry(registryBytes            )                       {
+  assertBytes(registryBytes, "registryBytes");
+  const parsed = JSON.parse(textDecoder.decode(registryBytes));
+
+  if (!isRecord(parsed)) {
+    throw new TypeError("registry must be a JSON object");
+  }
+
+  const entries = new Map                       ();
+  const revoked = parseRevoked(parsed.revoked);
+
+  for (const [kidHex, value] of Object.entries(parsed)) {
+    if (kidHex === "revoked") {
+      continue;
+    }
+
+    assertKidHex(kidHex, "registry kid");
+
+    if (!isRecord(value)) {
+      throw new TypeError(`registry entry ${kidHex} must be an object`);
+    }
+
+    const serviceIdentifier = value.service_identifier;
+    if (typeof serviceIdentifier !== "string" || serviceIdentifier.length === 0) {
+      throw new TypeError(`registry entry ${kidHex} service_identifier must be a non-empty string`);
+    }
+
+    const encodedPublicKey = value.public_key_ed25519;
+    if (typeof encodedPublicKey !== "string") {
+      throw new TypeError(`registry entry ${kidHex} public_key_ed25519 must be a string`);
+    }
+
+    const publicKeyEd25519 = base64urlDecodeFixed32(
+      encodedPublicKey,
+      `registry entry ${kidHex} public_key_ed25519`,
+    );
+
+    entries.set(kidHex, {
+      kidHex,
+      serviceIdentifier,
+      publicKeyEd25519,
+    });
+  }
+
+  return { entries, revoked };
+}
+
+export function resolveServiceKey(
+  registry                      ,
+  kid            ,
+)                {
+  const kidHex = toHex(kid);
+  const entry = registry.entries.get(kidHex);
+
+  if (!entry) {
+    throw new TypeError(`unknown kid ${kidHex}`);
+  }
+
+  return {
+    kidHex: entry.kidHex,
+    serviceIdentifier: entry.serviceIdentifier,
+    publicKeyEd25519: new Uint8Array(entry.publicKeyEd25519),
+  };
+}
+
+export function assertKeyNotRevoked(
+  registry                      ,
+  kid            ,
+  integratedTime                ,
+)       {
+  const kidHex = toHex(kid);
+  const revoked = registry.revoked.get(kidHex);
+
+  if (!revoked) {
+    return;
+  }
+
+  if (integratedTime === undefined) {
+    throw new TypeError(`kid ${kidHex} is revoked and requires verifiable integrated time`);
+  }
+
+  const integratedTimeMs =
+    integratedTime instanceof Date
+      ? integratedTime.getTime()
+      : parseUtcTimestamp(integratedTime, "integratedTime");
+  const revokedAtMs = parseUtcTimestamp(revoked.revokedAt, `revoked_at for ${kidHex}`);
+
+  if (integratedTimeMs >= revokedAtMs) {
+    throw new TypeError(`kid ${kidHex} was revoked at ${revoked.revokedAt}`);
+  }
+}
+
+function parseRevoked(value         )                               {
+  const revoked = new Map                         ();
+
+  if (value === undefined) {
+    return revoked;
+  }
+
+  if (!isRecord(value)) {
+    throw new TypeError("registry revoked must be an object");
+  }
+
+  for (const [kidHex, entry] of Object.entries(value)) {
+    assertKidHex(kidHex, "revoked kid");
+
+    if (!isRecord(entry) || typeof entry.revoked_at !== "string") {
+      throw new TypeError(`revoked entry ${kidHex} must contain revoked_at`);
+    }
+
+    parseUtcTimestamp(entry.revoked_at, `revoked_at for ${kidHex}`);
+    revoked.set(kidHex, { kidHex, revokedAt: entry.revoked_at });
+  }
+
+  return revoked;
+}
+
+function base64urlEncode(bytes            )         {
+  return Buffer.from(bytes).toString("base64url");
+}
+
+function base64urlDecodeFixed32(value        , name        )             {
+  if (value.length !== BASE64URL_32_BYTE_LENGTH) {
+    throw new TypeError(`${name} must be base64url encoding of 32 bytes`);
+  }
+
+  const decoded = base64urlDecode(value, name);
+  assertEd25519PublicKey(decoded, name);
+  return decoded;
+}
+
+function base64urlDecode(value        , name        )             {
+  if (!/^[A-Za-z0-9_-]+$/.test(value) || value.length % 4 === 1) {
+    throw new TypeError(`${name} must be unpadded base64url`);
+  }
+
+  return Uint8Array.from(Buffer.from(value, "base64url"));
+}
+
+function assertKidHex(value        , name        )       {
+  if (!/^(?:[0-9a-f]{2})+$/.test(value)) {
+    throw new TypeError(`${name} must be lowercase even-length hex`);
+  }
+}
+
+function parseUtcTimestamp(value        , name        )         {
+  if (
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(value) ||
+    Number.isNaN(Date.parse(value))
+  ) {
+    throw new TypeError(`${name} must be an RFC 3339 UTC timestamp`);
+  }
+
+  return Date.parse(value);
+}
+
+function assertBytes(value         , name        )                              {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+}
+
+function isRecord(value         )                                   {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/sdk/index.js

@@ -0,0 +1,22 @@
+import { createSelloService } from "./service.js";
+import * as logs from "./logs.js";
+
+export const sello = {
+  service: createSelloService,
+  logs,
+};
+
+export { createSelloService };
+export {
+  decodeBase64url,
+  encodeOwnerKey,
+  encodeServiceKey,
+  normalizeEd25519PrivateKey,
+  normalizeEd25519PublicKey,
+  normalizeHpkePrivateKey,
+  normalizeKid,
+  normalizeServiceKey,
+} from "./keys.js";
+export * from "./logs.js";
+export * from "./publisher.js";
+export * from "./service.js";

package/dist/sdk/keys.js

@@ -0,0 +1,191 @@
+import {
+  assertEd25519PrivateKey,
+  assertEd25519PublicKey,
+} from "../crypto/ed25519.js";
+
+                                           
+
+                             
+          
+     
+                    
+                           
+      
+
+                                    
+                  
+                         
+  
+
+const textEncoder = new TextEncoder();
+
+export function normalizeServiceKey(
+  input                             ,
+  fallbackKid           ,
+)                       {
+  if (input === undefined) {
+    throw new TypeError("SELLO_SERVICE_KEY is required");
+  }
+
+  if (typeof input === "object" && !(input instanceof Uint8Array)) {
+    const kid = normalizeKid(input.kid, "serviceKey.kid");
+    const privateKey = normalizeEd25519PrivateKey(
+      input.privateKey,
+      "serviceKey.privateKey",
+    );
+    return { kid, privateKey };
+  }
+
+  if (typeof input !== "string") {
+    throw new TypeError("serviceKey must be a string or { kid, privateKey }");
+  }
+
+  const encoded = stripKnownServiceKeyPrefix(input);
+  const separator = encoded.indexOf(".");
+  if (separator !== -1) {
+    const kid = decodeBase64url(encoded.slice(0, separator), "service key kid");
+    const privateKey = normalizeEd25519PrivateKey(
+      encoded.slice(separator + 1),
+      "service key private key",
+    );
+    return { kid, privateKey };
+  }
+
+  if (fallbackKid === undefined) {
+    throw new TypeError(
+      "SELLO_SERVICE_KEY must include a kid, or SELLO_SERVICE_KID must be set",
+    );
+  }
+
+  return {
+    kid: normalizeKid(fallbackKid, "service kid"),
+    privateKey: normalizeEd25519PrivateKey(input, "service key private key"),
+  };
+}
+
+export function encodeServiceKey(
+  kid            ,
+  privateKey            ,
+  prefix = "sello_dev",
+)         {
+  assertBytes(kid, "kid");
+  assertEd25519PrivateKey(privateKey, "privateKey");
+  return `${prefix}_${base64urlEncode(kid)}.${base64urlEncode(privateKey)}`;
+}
+
+export function normalizeKid(input          , name = "kid")             {
+  if (input instanceof Uint8Array) {
+    if (input.byteLength === 0) {
+      throw new TypeError(`${name} must not be empty`);
+    }
+    return new Uint8Array(input);
+  }
+
+  if (typeof input !== "string" || input.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string or Uint8Array`);
+  }
+
+  return textEncoder.encode(input);
+}
+
+export function normalizeEd25519PrivateKey(
+  input          ,
+  name = "privateKey",
+)             {
+  const key = normalizeFixedBase64urlKey(input, 32, name);
+  assertEd25519PrivateKey(key, name);
+  return key;
+}
+
+export function normalizeEd25519PublicKey(
+  input          ,
+  name = "publicKey",
+)             {
+  const key = normalizeFixedBase64urlKey(input, 32, name);
+  assertEd25519PublicKey(key, name);
+  return key;
+}
+
+export function normalizeHpkePrivateKey(
+  input          ,
+  name = "ownerPrivateKey",
+)             {
+  return normalizeFixedBase64urlKey(stripKnownOwnerKeyPrefix(input), 32, name);
+}
+
+export function encodeOwnerKey(privateKey            , prefix = "sello_owner_dev")         {
+  assertByteLength(privateKey, 32, "privateKey");
+  return `${prefix}_${base64urlEncode(privateKey)}`;
+}
+
+export function base64urlEncode(bytes            )         {
+  assertBytes(bytes, "bytes");
+  return Buffer.from(bytes).toString("base64url");
+}
+
+export function decodeBase64url(value        , name = "value")             {
+  if (!/^[A-Za-z0-9_-]+$/.test(value) || value.length % 4 === 1) {
+    throw new TypeError(`${name} must be unpadded base64url`);
+  }
+
+  return Uint8Array.from(Buffer.from(value, "base64url"));
+}
+
+function normalizeFixedBase64urlKey(
+  input          ,
+  length        ,
+  name        ,
+)             {
+  if (input instanceof Uint8Array) {
+    assertByteLength(input, length, name);
+    return new Uint8Array(input);
+  }
+
+  if (typeof input !== "string") {
+    throw new TypeError(`${name} must be a string or Uint8Array`);
+  }
+
+  const decoded = decodeBase64url(input, name);
+  assertByteLength(decoded, length, name);
+  return decoded;
+}
+
+function stripKnownServiceKeyPrefix(input        )         {
+  for (const prefix of ["sello_dev_", "sello_live_local_"]) {
+    if (input.startsWith(prefix)) {
+      return input.slice(prefix.length);
+    }
+  }
+
+  return input;
+}
+
+function stripKnownOwnerKeyPrefix(input          )           {
+  if (typeof input !== "string") {
+    return input;
+  }
+
+  for (const prefix of ["sello_owner_dev_", "sello_owner_live_"]) {
+    if (input.startsWith(prefix)) {
+      return input.slice(prefix.length);
+    }
+  }
+
+  return input;
+}
+
+function assertByteLength(
+  value         ,
+  length        ,
+  name        ,
+)                              {
+  if (!(value instanceof Uint8Array) || value.byteLength !== length) {
+    throw new TypeError(`${name} must be a ${length}-byte Uint8Array`);
+  }
+}
+
+function assertBytes(value         , name        )                              {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+}