@fide.work/fcp 0.0.1-alpha.0

package/dist/statement/build.d.ts

@@ -0,0 +1,99 @@
+/**
+ * FCP SDK Statement Building Utilities
+ *
+ * Helpers for creating statement objects with proper structure.
+ */
+import type { FideId, FideEntityType, FideStatementPredicateEntityType, FideStatementPredicateSourceType } from "../fide-id/types.js";
+/**
+ * Input for creating a statement.
+ *
+ * All triples require rawIdentifier + entityType + sourceType. The SDK always computes
+ * Fide IDs internally to avoid trust/validation issues with pre-calculated hashes.
+ */
+export interface StatementInput {
+    /** Subject - raw identifier with entity type and source type */
+    subject: {
+        rawIdentifier: string;
+        entityType: FideEntityType;
+        sourceType: FideEntityType;
+    };
+    /**
+     * Predicate - explicit raw identifier with entity type and source type.
+     * `rawIdentifier` must be a canonical full URL (https://...).
+     * Entity type must be CreativeWork.
+     */
+    predicate: {
+        rawIdentifier: string;
+        entityType: FideStatementPredicateEntityType;
+        sourceType: FideStatementPredicateSourceType;
+    };
+    /** Object - raw identifier with entity type and source type */
+    object: {
+        rawIdentifier: string;
+        entityType: FideEntityType;
+        sourceType: FideEntityType;
+    };
+    /** If true, skip URL normalization for raw identifiers while keeping predicate URL validation. */
+    ifSkipNormalizeUrl?: boolean;
+}
+/**
+ * Complete statement object with all required fields
+ *
+ * **Important**: Both Fide IDs and raw identifiers are required because:
+ * - Fide IDs are one-way hashes - cannot be reversed to get raw identifiers
+ * - Protocol specification requires both fields
+ * - Indexers need raw identifiers for lookup tables and human-readable display
+ * - Enables mapping back to human-readable identifiers for debugging and display
+ */
+export interface Statement {
+    /** Subject Fide ID */
+    subjectFideId: FideId;
+    /** Subject raw identifier (required - cannot be derived from Fide ID) */
+    subjectRawIdentifier: string;
+    /** Predicate Fide ID */
+    predicateFideId: FideId;
+    /** Predicate raw identifier (required - cannot be derived from Fide ID) */
+    predicateRawIdentifier: string;
+    /** Object Fide ID */
+    objectFideId: FideId;
+    /** Object raw identifier (required - cannot be derived from Fide ID) */
+    objectRawIdentifier: string;
+    /** Statement Fide ID (calculated) */
+    statementFideId?: FideId;
+}
+/**
+ * Batch build result with deterministic content root.
+ */
+export interface StatementBatchWithRoot {
+    statements: Statement[];
+    statementFideIds: FideId[];
+    /** Deterministic SHA-256 hex hash of ordered statement Fide IDs. */
+    root: string;
+}
+/**
+ * Create a statement object with all required fields.
+ *
+ * Always computes Fide IDs from rawIdentifier + entityType + sourceType.
+ * Predicates must be canonical full URLs.
+ *
+ * @param input - Statement input with subject, predicate, and object
+ * @paramDefault input { subject: { rawIdentifier: "https://x.com/alice", entityType: "Person", sourceType: "Product" }, predicate: { rawIdentifier: "https://schema.org/name", entityType: "CreativeWork", sourceType: "Product" }, object: { rawIdentifier: "Alice", entityType: "CreativeWork", sourceType: "CreativeWork" } }
+ * @returns Complete statement object
+ * @throws Error if statement input policy fails, Fide ID format/policy checks fail, or statement ID derivation fails
+ */
+export declare function createStatement(input: StatementInput): Promise<Statement>;
+/**
+ * Build a batch of statements and derive a deterministic batch root.
+ *
+ * Root derivation:
+ * - `statementFideIds` are lexicographically sorted
+ * - Sorted IDs are joined with `\\n`
+ * - SHA-256 is computed over that byte sequence
+ * - Result is returned as lowercase hex string
+ *
+ * @param inputs Array of statement inputs.
+ * @paramDefault inputs [{ subject: { rawIdentifier: "https://x.com/alice", entityType: "Person", sourceType: "Product" }, predicate: { rawIdentifier: "https://schema.org/name", entityType: "CreativeWork", sourceType: "Product" }, object: { rawIdentifier: "Alice", entityType: "CreativeWork", sourceType: "CreativeWork" } }, { subject: { rawIdentifier: "https://x.com/bob", entityType: "Person", sourceType: "Product" }, predicate: { rawIdentifier: "https://schema.org/worksFor", entityType: "CreativeWork", sourceType: "Product" }, object: { rawIdentifier: "https://www.acme.com", entityType: "Organization", sourceType: "Product" } }]
+ * @returns Statements, statement IDs (input order), and deterministic root hash
+ * @throws Error if one or more built statements are missing `statementFideId`
+ */
+export declare function batchStatementsWithRoot(inputs: StatementInput[]): Promise<StatementBatchWithRoot>;

package/dist/statement/build.js

@@ -0,0 +1,71 @@
+/**
+ * FCP SDK Statement Building Utilities
+ *
+ * Helpers for creating statement objects with proper structure.
+ */
+import { calculateFideId, calculateStatementFideId } from "../fide-id/index.js";
+import { assertStatementFideIdsPolicy, assertStatementInputPolicy, normalizeIfUrlLike, normalizePredicateRawIdentifier } from "./policy.js";
+import { createHash } from "node:crypto";
+/**
+ * Create a statement object with all required fields.
+ *
+ * Always computes Fide IDs from rawIdentifier + entityType + sourceType.
+ * Predicates must be canonical full URLs.
+ *
+ * @param input - Statement input with subject, predicate, and object
+ * @paramDefault input { subject: { rawIdentifier: "https://x.com/alice", entityType: "Person", sourceType: "Product" }, predicate: { rawIdentifier: "https://schema.org/name", entityType: "CreativeWork", sourceType: "Product" }, object: { rawIdentifier: "Alice", entityType: "CreativeWork", sourceType: "CreativeWork" } }
+ * @returns Complete statement object
+ * @throws Error if statement input policy fails, Fide ID format/policy checks fail, or statement ID derivation fails
+ */
+export async function createStatement(input) {
+    assertStatementInputPolicy(input);
+    const ifSkipNormalizeUrl = input.ifSkipNormalizeUrl === true;
+    const subjectRawIdentifier = normalizeIfUrlLike(input.subject.rawIdentifier, ifSkipNormalizeUrl);
+    const predicateRawIdentifier = normalizePredicateRawIdentifier(input.predicate.rawIdentifier, ifSkipNormalizeUrl);
+    const objectRawIdentifier = normalizeIfUrlLike(input.object.rawIdentifier, ifSkipNormalizeUrl);
+    const subjectFideId = await calculateFideId(input.subject.entityType, input.subject.sourceType, subjectRawIdentifier);
+    const predicateFideId = await calculateFideId(input.predicate.entityType, input.predicate.sourceType, predicateRawIdentifier);
+    const objectFideId = await calculateFideId(input.object.entityType, input.object.sourceType, objectRawIdentifier);
+    assertStatementFideIdsPolicy(subjectFideId, predicateFideId, objectFideId);
+    // Calculate statement Fide ID
+    const statementFideId = await calculateStatementFideId(subjectFideId, predicateFideId, objectFideId);
+    return {
+        subjectFideId,
+        subjectRawIdentifier,
+        predicateFideId,
+        predicateRawIdentifier,
+        objectFideId,
+        objectRawIdentifier,
+        statementFideId
+    };
+}
+/**
+ * Build a batch of statements and derive a deterministic batch root.
+ *
+ * Root derivation:
+ * - `statementFideIds` are lexicographically sorted
+ * - Sorted IDs are joined with `\\n`
+ * - SHA-256 is computed over that byte sequence
+ * - Result is returned as lowercase hex string
+ *
+ * @param inputs Array of statement inputs.
+ * @paramDefault inputs [{ subject: { rawIdentifier: "https://x.com/alice", entityType: "Person", sourceType: "Product" }, predicate: { rawIdentifier: "https://schema.org/name", entityType: "CreativeWork", sourceType: "Product" }, object: { rawIdentifier: "Alice", entityType: "CreativeWork", sourceType: "CreativeWork" } }, { subject: { rawIdentifier: "https://x.com/bob", entityType: "Person", sourceType: "Product" }, predicate: { rawIdentifier: "https://schema.org/worksFor", entityType: "CreativeWork", sourceType: "Product" }, object: { rawIdentifier: "https://www.acme.com", entityType: "Organization", sourceType: "Product" } }]
+ * @returns Statements, statement IDs (input order), and deterministic root hash
+ * @throws Error if one or more built statements are missing `statementFideId`
+ */
+export async function batchStatementsWithRoot(inputs) {
+    const statements = await Promise.all(inputs.map((input) => createStatement(input)));
+    const statementFideIds = statements
+        .map((s) => s.statementFideId)
+        .filter((id) => !!id);
+    if (statementFideIds.length !== statements.length) {
+        throw new Error("Batch build failed: one or more statements are missing statementFideId.");
+    }
+    const canonicalIds = [...statementFideIds].sort();
+    const root = createHash("sha256").update(canonicalIds.join("\n")).digest("hex");
+    return {
+        statements,
+        statementFideIds,
+        root
+    };
+}

package/dist/statement/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * FCP SDK - Statement Module
+ *
+ * Re-exports all statement utilities.
+ */
+export { createStatement, batchStatementsWithRoot, type StatementInput, type Statement, type StatementBatchWithRoot } from "./build.js";

package/dist/statement/index.js

@@ -0,0 +1,6 @@
+/**
+ * FCP SDK - Statement Module
+ *
+ * Re-exports all statement utilities.
+ */
+export { createStatement, batchStatementsWithRoot } from "./build.js";

package/dist/statement/policy.d.ts

@@ -0,0 +1,33 @@
+import type { StatementInput } from "./build.js";
+/**
+ * Enforce statement input policy before deriving Fide IDs.
+ */
+export declare function assertStatementInputPolicy(input: StatementInput): void;
+/**
+ * Normalize rawIdentifier only when it is URL-like (http/https).
+ *
+ * Rules for URL-like values:
+ * - must parse as an absolute URL
+ * - lowercase scheme + host
+ * - remove default ports (80 for http, 443 for https)
+ * - preserve path/query/fragment case
+ *
+ * Non URL-like values are returned unchanged.
+ */
+export declare function normalizeIfUrlLike(rawIdentifier: string, ifSkipNormalizeUrl?: boolean): string;
+/**
+ * Canonicalize and validate predicate rawIdentifier URLs.
+ *
+ * Policy:
+ * - must be an absolute URL
+ * - must use https
+ * - username/password are not allowed
+ * - normalize scheme + host case only
+ * - remove default https port (443)
+ * - preserve path/query/fragment case
+ */
+export declare function normalizePredicateRawIdentifier(rawIdentifier: string, ifSkipNormalizeUrl?: boolean): string;
+/**
+ * Enforce statement ID policy after deriving subject/predicate/object Fide IDs.
+ */
+export declare function assertStatementFideIdsPolicy(subjectFideId: string, predicateFideId: string, objectFideId: string): void;

package/dist/statement/policy.js

@@ -0,0 +1,183 @@
+import { assertFideId, parseFideId } from "../fide-id/index.js";
+function describeValue(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    const kind = typeof value;
+    if (kind === "string")
+        return `string(${JSON.stringify(value)})`;
+    if (kind === "number" || kind === "boolean" || kind === "bigint")
+        return `${kind}(${String(value)})`;
+    if (kind === "function")
+        return "function";
+    if (Array.isArray(value))
+        return `array(len=${value.length})`;
+    if (kind === "object") {
+        try {
+            return `object(${JSON.stringify(value)})`;
+        }
+        catch {
+            return "object([unserializable])";
+        }
+    }
+    return kind;
+}
+/**
+ * Enforce statement input policy before deriving Fide IDs.
+ */
+export function assertStatementInputPolicy(input) {
+    if (!input || typeof input !== "object") {
+        throw new Error(`Invalid statement input: expected object with subject, predicate, and object; got ${describeValue(input)}.`);
+    }
+    if (!input.subject || typeof input.subject !== "object") {
+        throw new Error(`Invalid statement input: expected subject object; got ${describeValue(input.subject)}.`);
+    }
+    if (!input.predicate || typeof input.predicate !== "object") {
+        throw new Error(`Invalid statement input: expected predicate object; got ${describeValue(input.predicate)}.`);
+    }
+    if (!input.object || typeof input.object !== "object") {
+        throw new Error(`Invalid statement input: expected object object at input.object; got ${describeValue(input.object)}.`);
+    }
+    if (typeof input.subject.rawIdentifier !== "string") {
+        throw new Error(`Invalid statement input: expected subject.rawIdentifier as string; got ${describeValue(input.subject?.rawIdentifier)}.`);
+    }
+    if (typeof input.subject.entityType !== "string") {
+        throw new Error(`Invalid statement input: expected subject.entityType as string; got ${describeValue(input.subject?.entityType)}.`);
+    }
+    if (typeof input.subject.sourceType !== "string") {
+        throw new Error(`Invalid statement input: expected subject.sourceType as string; got ${describeValue(input.subject?.sourceType)}.`);
+    }
+    if (typeof input.predicate.rawIdentifier !== "string") {
+        throw new Error(`Invalid statement input: expected predicate.rawIdentifier as string; got ${describeValue(input.predicate?.rawIdentifier)}.`);
+    }
+    if (typeof input.predicate.entityType !== "string") {
+        throw new Error(`Invalid statement input: expected predicate.entityType as string; got ${describeValue(input.predicate?.entityType)}.`);
+    }
+    if (typeof input.predicate.sourceType !== "string") {
+        throw new Error(`Invalid statement input: expected predicate.sourceType as string; got ${describeValue(input.predicate?.sourceType)}.`);
+    }
+    if (typeof input.object.rawIdentifier !== "string") {
+        throw new Error(`Invalid statement input: expected object.rawIdentifier as string; got ${describeValue(input.object?.rawIdentifier)}.`);
+    }
+    if (typeof input.object.entityType !== "string") {
+        throw new Error(`Invalid statement input: expected object.entityType as string; got ${describeValue(input.object?.entityType)}.`);
+    }
+    if (typeof input.object.sourceType !== "string") {
+        throw new Error(`Invalid statement input: expected object.sourceType as string; got ${describeValue(input.object?.sourceType)}.`);
+    }
+    if (input.predicate.entityType !== "CreativeWork") {
+        throw new Error(`Invalid predicate entityType: ${input.predicate.entityType}. Expected CreativeWork.`);
+    }
+    if (input.predicate.sourceType !== "Product") {
+        throw new Error(`Invalid predicate sourceType: ${input.predicate.sourceType}. Expected Product.`);
+    }
+    // Predicate URL validity/canonicalization is enforced by normalizePredicateRawIdentifier()
+    // in the statement building path.
+}
+/**
+ * Normalize rawIdentifier only when it is URL-like (http/https).
+ *
+ * Rules for URL-like values:
+ * - must parse as an absolute URL
+ * - lowercase scheme + host
+ * - remove default ports (80 for http, 443 for https)
+ * - preserve path/query/fragment case
+ *
+ * Non URL-like values are returned unchanged.
+ */
+export function normalizeIfUrlLike(rawIdentifier, ifSkipNormalizeUrl = false) {
+    if (ifSkipNormalizeUrl) {
+        return rawIdentifier;
+    }
+    if (!/^https?:\/\//i.test(rawIdentifier)) {
+        return rawIdentifier;
+    }
+    let url;
+    try {
+        url = new URL(rawIdentifier);
+    }
+    catch {
+        throw new Error(`Invalid URL-like rawIdentifier: ${rawIdentifier}. Expected absolute URL when using http(s) format.`);
+    }
+    const protocol = url.protocol.toLowerCase();
+    if (protocol !== "http:" && protocol !== "https:") {
+        return rawIdentifier;
+    }
+    url.protocol = protocol;
+    url.hostname = url.hostname.toLowerCase();
+    if ((protocol === "https:" && url.port === "443") || (protocol === "http:" && url.port === "80")) {
+        url.port = "";
+    }
+    return url.toString();
+}
+/**
+ * Canonicalize and validate predicate rawIdentifier URLs.
+ *
+ * Policy:
+ * - must be an absolute URL
+ * - must use https
+ * - username/password are not allowed
+ * - normalize scheme + host case only
+ * - remove default https port (443)
+ * - preserve path/query/fragment case
+ */
+export function normalizePredicateRawIdentifier(rawIdentifier, ifSkipNormalizeUrl = false) {
+    if (ifSkipNormalizeUrl) {
+        let skipUrl;
+        try {
+            skipUrl = new URL(rawIdentifier);
+        }
+        catch {
+            throw new Error(`Invalid predicate rawIdentifier: ${rawIdentifier}. Expected canonical full URL (e.g. https://schema.org/name).`);
+        }
+        if (skipUrl.protocol.toLowerCase() !== "https:") {
+            throw new Error(`Invalid predicate rawIdentifier protocol: ${rawIdentifier}. Expected https URL.`);
+        }
+        if (skipUrl.username || skipUrl.password) {
+            throw new Error(`Invalid predicate rawIdentifier: ${rawIdentifier}. URL userinfo is not allowed.`);
+        }
+        return rawIdentifier;
+    }
+    const normalized = normalizeIfUrlLike(rawIdentifier, ifSkipNormalizeUrl);
+    let url;
+    try {
+        url = new URL(normalized);
+    }
+    catch {
+        throw new Error(`Invalid predicate rawIdentifier: ${rawIdentifier}. Expected canonical full URL (e.g. https://schema.org/name).`);
+    }
+    if (url.protocol.toLowerCase() !== "https:") {
+        throw new Error(`Invalid predicate rawIdentifier protocol: ${rawIdentifier}. Expected https URL.`);
+    }
+    if (url.username || url.password) {
+        throw new Error(`Invalid predicate rawIdentifier: ${rawIdentifier}. URL userinfo is not allowed.`);
+    }
+    url.protocol = "https:";
+    url.hostname = url.hostname.toLowerCase();
+    if (url.port === "443") {
+        url.port = "";
+    }
+    return url.toString();
+}
+/**
+ * Enforce statement ID policy after deriving subject/predicate/object Fide IDs.
+ */
+export function assertStatementFideIdsPolicy(subjectFideId, predicateFideId, objectFideId) {
+    // Predicate combo policy is enforced at input level (entityType/sourceType).
+    // Keep ID-level checks here for subject/object Statement-source restrictions.
+    assertRoleFideIdPolicy(subjectFideId, "subject");
+    assertRoleFideIdPolicy(objectFideId, "object");
+}
+function assertRoleFideIdPolicy(fideId, role) {
+    assertFideId(fideId);
+    const { typeChar, sourceChar } = parseFideId(fideId);
+    if (sourceChar !== "0")
+        return;
+    if (typeChar === "0")
+        return;
+    const label = role ? ` ${role}` : "";
+    throw new Error(`Invalid Fide ID for statement${label}: ${fideId}. ` +
+        `Protocol disallows Statement source (0xX0) for non-Statement entities. ` +
+        `Use a concrete source (e.g. Product 0x15, Organization 0x25) instead of Statement-derived IDs.`);
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@fide.work/fcp",
+  "version": "0.0.1-alpha.0",
+  "description": "Fide Context Protocol SDK (v0)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fide-work/fcp.git"
+  },
+  "homepage": "https://fide.work/fcp",
+  "keywords": [
+    "fide",
+    "fcp",
+    "did",
+    "identity",
+    "contest",
+    "memory"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.9.3",
+    "viem": "^2.21.48"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc --noEmit",
+    "test": "pnpm run build && node scripts/test-runner.mjs",
+    "test:verbose": "pnpm run build && node scripts/test-runner.mjs --verbose",
+    "experimental:guard": "node -e \"if (process.env.FCP_EXPERIMENTAL !== '1') { console.error('Experimental examples are disabled. Re-run with FCP_EXPERIMENTAL=1'); process.exit(1); }\"",
+    "example": "pnpm run build && node examples/fide-id/basic-usage.mjs",
+    "example:fide-id": "pnpm run build && node examples/fide-id/basic-usage.mjs",
+    "example:statement": "pnpm run build && node examples/statement/statement-example.mjs",
+    "example:experimental": "pnpm run experimental:guard && pnpm run build && node scripts/run-experimental-example.mjs",
+    "example:schema": "pnpm run build && node examples/schema/schema-example.mjs"
+  }
+}