@tinycloud/sdk-core 3.0.0-beta.0 → 3.0.0-beta.1

package/dist/index.cjs

@@ -136,6 +136,7 @@ __export(index_exports, {
   NETWORK_NAME_PATTERN: () => import_sdk_services8.NETWORK_NAME_PATTERN,
   NetworkIdError: () => import_sdk_services8.NetworkIdError,
   OPENKEY_ACTION_ID_SEPARATOR: () => OPENKEY_ACTION_ID_SEPARATOR,
+  OpenKeyManageKeyError: () => OpenKeyManageKeyError,
   POLICY_CAPABILITY_V1_DOMAIN: () => POLICY_CAPABILITY_V1_DOMAIN,
   POLICY_CAPABILITY_V1_SCHEMA: () => POLICY_CAPABILITY_V1_SCHEMA,
   POLICY_CREDENTIAL_REQUIREMENT_V1_TYPE: () => POLICY_CREDENTIAL_REQUIREMENT_V1_TYPE,
@@ -206,7 +207,9 @@ __export(index_exports, {
   SpaceService: () => SpaceService,
   TINYCLOUD_ACCOUNT_SPACE_MANIFEST: () => import_bootstrap4.TINYCLOUD_ACCOUNT_SPACE_MANIFEST,
   TINYCLOUD_APPLICATIONS_SPACE_MANIFEST: () => import_bootstrap4.TINYCLOUD_APPLICATIONS_SPACE_MANIFEST,
+  TINYCLOUD_CANONICAL_IDENTITY_CLAIM: () => TINYCLOUD_CANONICAL_IDENTITY_CLAIM,
   TINYCLOUD_DEFAULT_SPACE_MANIFEST: () => import_bootstrap4.TINYCLOUD_DEFAULT_SPACE_MANIFEST,
+  TINYCLOUD_MANAGE_KEY_SCOPE: () => TINYCLOUD_MANAGE_KEY_SCOPE,
   TINYCLOUD_PUBLIC_SPACE_MANIFEST: () => import_bootstrap4.TINYCLOUD_PUBLIC_SPACE_MANIFEST,
   TINYCLOUD_SECRETS_BOOTSTRAP_MANIFEST: () => import_bootstrap4.TINYCLOUD_SECRETS_BOOTSTRAP_MANIFEST,
   TinyCloud: () => TinyCloud,
@@ -267,6 +270,7 @@ __export(index_exports, {
   createInMemoryLocalNodeIdentityStore: () => createInMemoryLocalNodeIdentityStore,
   createLocalStorageLocalNodeIdentityStore: () => createLocalStorageLocalNodeIdentityStore,
   createOpenKeyCallbackSigningStrategy: () => createOpenKeyCallbackSigningStrategy,
+  createOpenKeyManageKeySigningStrategy: () => createOpenKeyManageKeySigningStrategy,
   createPolicyEnforcementDelegation: () => createPolicyEnforcementDelegation,
   createShareArtifact: () => createShareArtifact,
   createShareArtifactAsync: () => createShareArtifactAsync,
@@ -325,6 +329,7 @@ __export(index_exports, {
   generateRandomReceiverKey: () => import_sdk_services8.generateRandomReceiverKey,
   getPolicyRootStatusV3: () => getPolicyRootStatusV3,
   getTinyCloudDebugLogs: () => import_sdk_services8.getTinyCloudDebugLogs,
+  hasTinyCloudManageKeyScope: () => hasTinyCloudManageKeyScope,
   hexDecode: () => import_sdk_services8.hexDecode,
   hexEncode: () => import_sdk_services8.hexEncode,
   holderBindingCanonicalBytes: () => holderBindingCanonicalBytes,
@@ -357,6 +362,8 @@ __export(index_exports, {
   openWrappedKey: () => import_sdk_services8.openWrappedKey,
   parseCanonicalNetworkId: () => parseCanonicalNetworkId,
   parseCanonicalRecapResource: () => parseCanonicalRecapResource,
+  parseCanonicalTinyCloudIdentity: () => parseCanonicalTinyCloudIdentity,
+  parseCanonicalTinyCloudIdentityClaims: () => parseCanonicalTinyCloudIdentityClaims,
   parseCompactUcanAuthorization: () => parseCompactUcanAuthorization,
   parseExpiry: () => parseExpiry,
   parseNetworkId: () => import_sdk_services8.parseNetworkId,
@@ -379,6 +386,7 @@ __export(index_exports, {
   projectUnifiedPolicyCapability: () => projectUnifiedPolicyCapability,
   recapCaveatsEqual: () => recapCaveatsEqual,
   renewPolicyRootStatusV3: () => renewPolicyRootStatusV3,
+  requestTinyCloudManageKeyScope: () => requestTinyCloudManageKeyScope,
   resolveCloudLocation: () => resolveCloudLocation,
   resolveManifest: () => resolveManifest,
   resolveManifestKnowledgeRoot: () => resolveManifestKnowledgeRoot,
@@ -15367,6 +15375,236 @@ function createOpenKeyCallbackSigningStrategy(options2) {
 }
 var defaultSignStrategy = { type: "auto-sign" };
 
+// src/authorization/manage-key.ts
+var TINYCLOUD_MANAGE_KEY_SCOPE = "tinycloud:manage-key";
+var TINYCLOUD_CANONICAL_IDENTITY_CLAIM = "https://tinycloud.xyz/canonical_identity";
+function requestTinyCloudManageKeyScope(scopes = []) {
+  const requested = typeof scopes === "string" ? scopes.split(/\s+/u) : scopes;
+  return [
+    ...new Set([...requested, TINYCLOUD_MANAGE_KEY_SCOPE].filter(Boolean))
+  ].sort().join(" ");
+}
+function hasTinyCloudManageKeyScope(scopes) {
+  const values = Array.isArray(scopes) ? scopes : typeof scopes === "string" ? scopes.split(/\s+/u) : [];
+  return values.includes(TINYCLOUD_MANAGE_KEY_SCOPE);
+}
+var OpenKeyManageKeyError = class extends Error {
+  constructor(code3, message, approvalUrl, retryable = false) {
+    super(message);
+    this.code = code3;
+    this.approvalUrl = approvalUrl;
+    this.retryable = retryable;
+    this.name = "OpenKeyManageKeyError";
+  }
+};
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function rejected(message) {
+  return new OpenKeyManageKeyError("MESSAGE_REJECTED", message);
+}
+function identityMismatch(message) {
+  return new OpenKeyManageKeyError("IDENTITY_MISMATCH", message);
+}
+function parseCanonicalTinyCloudIdentity(value) {
+  if (!isRecord2(value))
+    throw rejected("Canonical TinyCloud identity is missing");
+  const expectedKeys = [
+    "address",
+    "chainId",
+    "did",
+    "keyId",
+    "spaceId",
+    "version"
+  ];
+  const actualKeys = Object.keys(value).sort();
+  if (actualKeys.length !== expectedKeys.length || actualKeys.some((key, index) => key !== expectedKeys[index])) {
+    throw rejected("Canonical TinyCloud identity has an invalid shape");
+  }
+  if (value.version !== "v1")
+    throw rejected("Canonical TinyCloud identity version is unsupported");
+  if (typeof value.keyId !== "string" || value.keyId.trim() === "") {
+    throw rejected("Canonical TinyCloud identity key ID is invalid");
+  }
+  if (typeof value.address !== "string") {
+    throw rejected("Canonical TinyCloud identity address is invalid");
+  }
+  let address;
+  try {
+    address = canonicalizeAddress(value.address);
+  } catch {
+    throw rejected("Canonical TinyCloud identity address is invalid");
+  }
+  if (address !== value.address) {
+    throw rejected(
+      "Canonical TinyCloud identity address must use EIP-55 checksum casing"
+    );
+  }
+  if (typeof value.chainId !== "number" || !Number.isSafeInteger(value.chainId) || value.chainId <= 0) {
+    throw rejected("Canonical TinyCloud identity chain ID is invalid");
+  }
+  const did = pkhDid(address, value.chainId);
+  const spacePrefix = `tinycloud:pkh:eip155:${value.chainId}:${address}:`;
+  if (typeof value.spaceId !== "string" || !value.spaceId.startsWith(spacePrefix)) {
+    throw rejected("Canonical TinyCloud identity space is invalid");
+  }
+  const spaceName = value.spaceId.slice(spacePrefix.length);
+  let spaceId;
+  try {
+    spaceId = makePkhSpaceId(address, value.chainId, spaceName);
+  } catch {
+    throw rejected("Canonical TinyCloud identity space is invalid");
+  }
+  if (value.did !== did || value.spaceId !== spaceId) {
+    throw rejected("Canonical TinyCloud identity does not match its address");
+  }
+  return {
+    version: "v1",
+    keyId: value.keyId,
+    address,
+    chainId: value.chainId,
+    did,
+    spaceId
+  };
+}
+function parseCanonicalTinyCloudIdentityClaims(claims) {
+  if (!isRecord2(claims)) throw rejected("OAuth claims are missing");
+  return parseCanonicalTinyCloudIdentity(
+    claims[TINYCLOUD_CANONICAL_IDENTITY_CLAIM]
+  );
+}
+function identitiesEqual(left, right) {
+  return left.version === right.version && left.keyId === right.keyId && left.address === right.address && left.chainId === right.chainId && left.did === right.did && left.spaceId === right.spaceId;
+}
+function errorForResponse(body, status) {
+  const message = body?.reason ?? body?.error ?? `OpenKey manage-key signing failed with HTTP ${status}`;
+  switch (body?.code ?? body?.error) {
+    case "missing_scope":
+    case "consent_required":
+      return new OpenKeyManageKeyError("CONSENT_REQUIRED", message, body?.approvalUrl);
+    case "client_disabled":
+    case "signing_disabled":
+    case "grant_disabled":
+      return new OpenKeyManageKeyError("GRANT_DISABLED", message, body?.approvalUrl);
+    case "user_exclusive":
+      return new OpenKeyManageKeyError("USER_EXCLUSIVE", message, body?.approvalUrl);
+    case "token_expired":
+    case "token_too_old":
+    case "invalid_token":
+    case "expired_token":
+      return new OpenKeyManageKeyError("TOKEN_EXPIRED", message, body?.approvalUrl);
+    case "canonical_key_unavailable":
+    case "signer_failed":
+      return new OpenKeyManageKeyError(
+        "SIGNER_UNAVAILABLE",
+        "The canonical key signer is temporarily unavailable",
+        void 0,
+        true
+      );
+    default:
+      return new OpenKeyManageKeyError(
+        status === 401 ? "TOKEN_EXPIRED" : "MESSAGE_REJECTED",
+        message,
+        body?.approvalUrl
+      );
+  }
+}
+async function resolveToken(token) {
+  const value = typeof token === "function" ? await token() : token;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new OpenKeyManageKeyError(
+      "CONSENT_REQUIRED",
+      "A manage-key OAuth bearer token is required"
+    );
+  }
+  return value;
+}
+function normalizeEndpoint(value) {
+  let endpoint;
+  try {
+    endpoint = new URL(value);
+  } catch {
+    throw rejected("OpenKey manage-key signing endpoint must be an absolute URL");
+  }
+  const rawHttpAuthority = value.match(/^http:\/\/([^/?#]*)/iu)?.[1];
+  const loopback = rawHttpAuthority !== void 0 && /^(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?$/u.test(rawHttpAuthority);
+  if (endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && loopback) || endpoint.username !== "" || endpoint.password !== "" || endpoint.search !== "" || endpoint.hash !== "") {
+    throw rejected("OpenKey manage-key signing endpoint must use HTTPS or exact loopback HTTP");
+  }
+  return endpoint.href;
+}
+function assertSignInRequest(request, identity3) {
+  if (request.type !== "siwe" || request.purpose !== "sign-in" || request.chainId !== identity3.chainId || request.address !== identity3.address || typeof request.message !== "string" || request.message.length === 0) {
+    throw rejected(
+      "Manage-key signing only permits the canonical sign-in SIWE request"
+    );
+  }
+}
+function createOpenKeyManageKeySigningStrategy(options2) {
+  const identity3 = parseCanonicalTinyCloudIdentity(options2.identity);
+  const endpoint = normalizeEndpoint(options2.endpoint);
+  return {
+    type: "callback",
+    openKeyAutoSign: true,
+    handler: async (request) => {
+      assertSignInRequest(request, identity3);
+      const fetchImpl = options2.fetch ?? globalThis.fetch;
+      if (!fetchImpl)
+        throw rejected("OpenKey manage-key signing requires fetch");
+      if (!hasTinyCloudManageKeyScope(options2.scopes)) {
+        throw new OpenKeyManageKeyError(
+          "CONSENT_REQUIRED",
+          "The OAuth bearer token was not granted tinycloud:manage-key"
+        );
+      }
+      const token = await resolveToken(options2.token);
+      const response = await fetchImpl(endpoint, {
+        method: "POST",
+        credentials: "omit",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({
+          address: request.address,
+          chainId: request.chainId,
+          message: request.message,
+          type: "siwe"
+        })
+      });
+      let body;
+      try {
+        const value = await response.json();
+        body = isRecord2(value) ? value : void 0;
+      } catch {
+        body = void 0;
+      }
+      if (!response.ok || body?.approved !== true)
+        throw errorForResponse(body, response.status);
+      if (typeof body.signature !== "string")
+        throw rejected("OpenKey manage-key signer did not return a signature");
+      const responseIdentity = parseCanonicalTinyCloudIdentity(
+        body.canonicalIdentity
+      );
+      if (!identitiesEqual(identity3, responseIdentity)) {
+        throw identityMismatch(
+          "OpenKey manage-key signer returned a different canonical identity"
+        );
+      }
+      if (!await verifyEip191MessageSignature(
+        request.message,
+        body.signature,
+        identity3.address
+      )) {
+        throw rejected(
+          "OpenKey manage-key signer returned an invalid signature"
+        );
+      }
+      return { approved: true, signature: body.signature };
+    }
+  };
+}
+
 // src/authorization/spaceCreation.ts
 var AutoApproveSpaceCreationHandler = class {
   /**