@tinycloud/mcp 0.8.3-beta.2 → 0.8.3-beta.20

package/dist/http-cli.js

@@ -33,7 +33,9 @@ function createOpenKeyTokenVerifier(config) {
           issuer: config.issuer,
           audience: config.audience
         });
-        return authInfo(token, payload, config);
+        const info = authInfo(token, payload, config);
+        if (config.tokenStatus !== void 0) await requireUsableStatus(config.tokenStatus, token);
+        return info;
       } catch (error) {
         if (error instanceof errors.JOSEError) {
           throw new OAuthError(OAuthErrorCode.InvalidToken, "The OpenKey access token is invalid.");
@@ -43,6 +45,16 @@ function createOpenKeyTokenVerifier(config) {
     }
   };
 }
+async function requireUsableStatus(checker, token) {
+  const status = await checker.tokenStatus(token);
+  if (status === "active") return;
+  if (status === "inactive") {
+    throw new OAuthError(OAuthErrorCode.InvalidToken, "The OpenKey access token is no longer active.");
+  }
+  if (!checker.toleratesUnknown(token)) {
+    throw new OAuthError(OAuthErrorCode.ServerError, "The OpenKey access token status is unavailable.");
+  }
+}
 async function loadOAuthMetadata(metadataUrl) {
   const response = await fetch(metadataUrl, {
     headers: { accept: "application/json" },
@@ -108,6 +120,150 @@ function firstString(...values) {
   return values.find((value) => typeof value === "string" && value.length > 0);
 }
 
+// src/token-status.ts
+import { createHash } from "crypto";
+import { decodeJwt } from "jose";
+var ACTIVE_CACHE_MS = 3e4;
+var DEFAULT_TOKEN_LIFETIME_SECONDS = 300;
+var DEFAULT_TIMEOUT_MS = 3e3;
+var MAX_CACHED_TOKENS = 1e4;
+function createTokenStatusChecker(config) {
+  const doFetch = config.fetch ?? fetch;
+  const clock = config.now ?? Date.now;
+  const log = config.log ?? ((message) => void process.stderr.write(`[tinycloud-mcp-http] ${message}
+`));
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const inactive = /* @__PURE__ */ new Map();
+  const active = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  const confirmedActive = /* @__PURE__ */ new Map();
+  let credentialsRefused = false;
+  async function introspect(token) {
+    const headers = {
+      accept: "application/json",
+      "content-type": "application/x-www-form-urlencoded"
+    };
+    const body = new URLSearchParams({ token, token_type_hint: "access_token" });
+    if (config.authMethod === "basic") {
+      const encode = (value) => encodeURIComponent(value).replace(/%20/g, "+");
+      const credentials = `${encode(config.clientId)}:${encode(config.clientSecret)}`;
+      headers.authorization = `Basic ${Buffer.from(credentials).toString("base64")}`;
+    } else {
+      body.set("client_id", config.clientId);
+      body.set("client_secret", config.clientSecret);
+    }
+    try {
+      const response = await doFetch(config.endpoint, {
+        method: "POST",
+        headers,
+        body,
+        redirect: "error",
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      if (response.status === 401) return "credentials";
+      if (response.status !== 200) return "unknown";
+      const result = await response.json();
+      if (typeof result !== "object" || result === null || !("active" in result)) return "unknown";
+      if (result.active === false) return "inactive";
+      if (result.active !== true) return "unknown";
+      return answerMatchesToken(Object.fromEntries(Object.entries(result)), token, config.resourceUrl) ? "active" : "mismatch";
+    } catch {
+      return "unknown";
+    }
+  }
+  async function query(key, token) {
+    const outcome = await introspect(token);
+    if (outcome === "credentials") {
+      if (!credentialsRefused) {
+        log("OpenKey token introspection refused the MCP client credentials (401); token checks fail closed until it accepts them.");
+      }
+      credentialsRefused = true;
+      return "unknown";
+    }
+    if (outcome === "unknown") return outcome;
+    const now = clock();
+    prune(now);
+    if (outcome === "mismatch") {
+      inactive.set(key, tokenExpiryMs(token, now));
+      confirmedActive.delete(key);
+      return "inactive";
+    }
+    credentialsRefused = false;
+    if (outcome === "inactive") {
+      inactive.set(key, tokenExpiryMs(token, now));
+      confirmedActive.delete(key);
+    } else {
+      active.set(key, now + ACTIVE_CACHE_MS);
+      confirmedActive.delete(key);
+      confirmedActive.set(key, { at: now, expiresAt: tokenExpiryMs(token, now) });
+    }
+    return outcome;
+  }
+  function prune(now) {
+    for (const [key, until] of active) if (until <= now) active.delete(key);
+    for (const [key, until] of inactive) if (until <= now) inactive.delete(key);
+    for (const [key, entry] of confirmedActive) if (entry.expiresAt <= now) confirmedActive.delete(key);
+    for (const cache of [active, inactive, confirmedActive]) {
+      while (cache.size >= MAX_CACHED_TOKENS) {
+        const oldest = cache.keys().next().value;
+        if (oldest === void 0) break;
+        cache.delete(oldest);
+      }
+    }
+  }
+  return {
+    async tokenStatus(token) {
+      const key = createHash("sha256").update(token).digest("hex");
+      const now = clock();
+      const inactiveUntil = inactive.get(key);
+      if (inactiveUntil !== void 0 && inactiveUntil > now) return "inactive";
+      const activeUntil = active.get(key);
+      if (activeUntil !== void 0 && activeUntil > now) return "active";
+      const pending = inFlight.get(key);
+      if (pending !== void 0) return pending;
+      const asking = query(key, token).finally(() => inFlight.delete(key));
+      inFlight.set(key, asking);
+      return asking;
+    },
+    toleratesUnknown(token) {
+      if (credentialsRefused) return false;
+      const confirmed = confirmedActive.get(createHash("sha256").update(token).digest("hex"));
+      if (confirmed === void 0) return false;
+      const now = clock();
+      return confirmed.expiresAt > now && now - confirmed.at < tokenLifetimeSeconds(token) * 1e3;
+    }
+  };
+}
+function answerMatchesToken(answer, token, resourceUrl) {
+  const jwt = claims(token);
+  if (typeof jwt.sub === "string" && answer.sub !== jwt.sub) return false;
+  const jwtClient = [jwt.azp, jwt.client_id].find((value) => typeof value === "string" && value.length > 0);
+  if (jwtClient !== void 0 && answer.client_id !== jwtClient) return false;
+  if (jwt.aud === void 0) return true;
+  const answered = audienceList(answer.aud);
+  const signed = audienceList(jwt.aud);
+  return answered.length > 0 && answered.includes(resourceUrl) && answered.every((entry) => signed.includes(entry));
+}
+function audienceList(value) {
+  const list = typeof value === "string" ? [value] : value;
+  return Array.isArray(list) && list.every((entry) => typeof entry === "string") ? list : [];
+}
+function tokenExpiryMs(token, now) {
+  const exp = claims(token).exp;
+  return typeof exp === "number" ? exp * 1e3 : now + DEFAULT_TOKEN_LIFETIME_SECONDS * 1e3;
+}
+function tokenLifetimeSeconds(token) {
+  const { exp, iat } = claims(token);
+  return typeof exp === "number" && typeof iat === "number" && exp > iat ? exp - iat : DEFAULT_TOKEN_LIFETIME_SECONDS;
+}
+function claims(token) {
+  try {
+    return decodeJwt(token);
+  } catch {
+    return {};
+  }
+}
+
 // src/logging.ts
 function logToolCall(tool, code, startedAt, replayedGrants) {
   process.stderr.write(`${JSON.stringify({
@@ -120,12 +276,15 @@ function logToolCall(tool, code, startedAt, replayedGrants) {
 }
 
 // src/remote-store.ts
-import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+import { createHmac, randomBytes, timingSafeEqual as timingSafeEqual2 } from "crypto";
 import { chmod, mkdir, readFile, readdir, rename, rm, writeFile } from "fs/promises";
 import { dirname, join } from "path";
 import {
+  activateValidatedRuntimeDelegation,
+  deserializeDelegation,
   InvalidRestoredSessionError,
   RuntimeDelegationRejectedError,
+  serializeDelegation,
   TinyCloudNode,
   UnsupportedSessionRestoreError,
   isCapabilitySubset,
@@ -134,11 +293,80 @@ import {
   signedCompactUcanExpiry
 } from "@tinycloud/node-sdk";
 import { TCWSessionManager, importKey, initPanicHook } from "@tinycloud/node-sdk-wasm";
+import { createOrReusePermissionRequest } from "@tinycloud/operations/artifacts";
+import { withTinyCloudStateRoot } from "@tinycloud/operations/state";
 import { invokeOperation } from "@tinycloud/operations";
 import { nodeRevocationOf, operationRetryDescriptor } from "@tinycloud/operations/mcp-authority";
 import { tcAppsApprovalMessage, tcAppsApprovalReason } from "@tinycloud/operations/tc-apps";
+
+// src/native-auth.ts
+import { timingSafeEqual } from "crypto";
+var NATIVE_SERVICE_CREDENTIAL_HEADER = "X-TinyCloud-Service-Credential";
+var NATIVE_OWNER_DID_HEADER = "X-TinyCloud-Owner-DID";
+var NATIVE_GRANT_MAX_LIFETIME_SECONDS = 30 * 24 * 60 * 60;
+var NATIVE_GRANT_REQUIRED = "native_grant_required";
+var NATIVE_GRANT_EXPIRED = "native_grant_expired";
+var NATIVE_GRANT_REJECTED = "native_grant_rejected";
+var NATIVE_SERVICE_UNAUTHORIZED = "native_service_unauthorized";
+var NATIVE_SERVICE_UNAVAILABLE = "native_service_unavailable";
+var NATIVE_GRANT_VALIDATION_UNAVAILABLE = "native_grant_validation_unavailable";
+var MAX_NATIVE_GRANT_BODY_BYTES = 256 * 1024;
+function serviceCredentialMatches(supplied, configured) {
+  if (supplied === null || configured === void 0) return false;
+  const suppliedBytes = Buffer.from(supplied, "utf8");
+  const configuredBytes = Buffer.from(configured, "utf8");
+  return suppliedBytes.byteLength === configuredBytes.byteLength && timingSafeEqual(suppliedBytes, configuredBytes);
+}
+var OWNER_APPLICATIONS_SPACE = /^tinycloud:pkh:eip155:([1-9][0-9]*):(0x[0-9a-f]{40}):applications$/i;
+var SQL_PATH = "xyz.tinycloud.tinychat/connectors";
+var KV_PREFIX = "xyz.tinycloud.tinychat/connectors/";
+function canonicalOwnerDid(value) {
+  const match = /^did:pkh:eip155:([1-9][0-9]*):(0x[0-9a-f]{40})$/i.exec(value);
+  if (!match) return void 0;
+  const chainId = Number(match[1]);
+  if (!Number.isSafeInteger(chainId)) return void 0;
+  return `did:pkh:eip155:${chainId}:${match[2].toLowerCase()}`;
+}
+function nativeOwnerForConnectorGrant(permissions) {
+  if (permissions.length !== 2) return void 0;
+  const sqlEntries = permissions.filter((permission) => permission.service === "tinycloud.sql");
+  const kvEntries = permissions.filter((permission) => permission.service === "tinycloud.kv");
+  if (sqlEntries.length !== 1 || kvEntries.length !== 1) return void 0;
+  const sql = sqlEntries[0];
+  const kv = kvEntries[0];
+  if (typeof sql.space !== "string" || typeof kv.space !== "string" || sql.path !== SQL_PATH || kv.path !== KV_PREFIX) return void 0;
+  if (!actionsEqual(sql.actions, ["tinycloud.sql/read"]) || !actionsEqual(kv.actions, ["tinycloud.kv/get", "tinycloud.kv/list"])) return void 0;
+  if (hasCaveats(sql) || hasCaveats(kv)) return void 0;
+  const sqlSpace = ownerFromApplicationsSpace(sql.space);
+  const kvSpace = ownerFromApplicationsSpace(kv.space);
+  return sqlSpace !== void 0 && sqlSpace === kvSpace ? sqlSpace : void 0;
+}
+function ownerFromApplicationsSpace(space) {
+  const match = OWNER_APPLICATIONS_SPACE.exec(space);
+  if (!match) return void 0;
+  const chainId = Number(match[1]);
+  if (!Number.isSafeInteger(chainId)) return void 0;
+  return `did:pkh:eip155:${chainId}:${match[2].toLowerCase()}`;
+}
+function actionsEqual(actual, expected) {
+  const actualActions = [...actual].sort();
+  const expectedActions = [...expected].sort();
+  return actualActions.length === expectedActions.length && actualActions.every((value, index) => value === expectedActions[index]);
+}
+function hasCaveats(permission) {
+  return Object.hasOwn(permission, "caveats") && permission.caveats !== void 0;
+}
+
+// src/remote-store.ts
 var PROFILE = "agent";
 var MAX_CALLBACK_BYTES = 256 * 1024;
+var NATIVE_GRANT_IMPORT_REJECTION_CODES = /* @__PURE__ */ new Set([
+  "DELEGATION_ARTIFACT_INVALID",
+  "DELEGATION_EXPIRED",
+  "DELEGATION_AUDIENCE_MISMATCH",
+  "DELEGATION_HOST_MISMATCH",
+  "DELEGATION_REJECTED"
+]);
 var LEGACY_DEFAULT_NODE_HOST = "https://node.tinycloud.xyz";
 var BOOTSTRAP_PERMISSIONS = [
   {
@@ -180,6 +408,15 @@ var ApprovalRequestError = class extends Error {
     this.detail = detail;
   }
 };
+var NativeGrantValidationError = class extends Error {
+  code;
+  constructor(status) {
+    const code = status.startsWith("native_") ? status : status === "required" ? "native_grant_required" : status === "expired" ? "native_grant_expired" : status === "unavailable" ? "native_grant_validation_unavailable" : "native_grant_rejected";
+    super(code);
+    this.name = "NativeGrantValidationError";
+    this.code = code;
+  }
+};
 var RemoteTenantStore = class {
   #config;
   #initializing = /* @__PURE__ */ new Map();
@@ -192,9 +429,186 @@ var RemoteTenantStore = class {
   #scopedClearing = /* @__PURE__ */ new Map();
   #clearedScoped = /* @__PURE__ */ new Map();
   #approvalProcessing = /* @__PURE__ */ new Map();
+  #nativeIdentity;
+  #nativeGrantQueues = /* @__PURE__ */ new Map();
   constructor(config) {
     this.#config = config;
   }
+  async nativeServiceIdentity() {
+    const identity = await this.#loadNativeServiceKey();
+    return { serviceDid: normalizeDid(identity.did) };
+  }
+  nativeTenantStateRoot(ownerDid) {
+    const canonical = canonicalOwnerDid(ownerDid);
+    if (canonical === void 0) throw new NativeGrantValidationError("rejected");
+    const tenant = createHmac("sha256", this.#config.stateSecret).update(`native-tenant:${canonical}`).digest("hex");
+    return join(this.#config.stateDir, "native-tenants", tenant);
+  }
+  async acceptNativeGrant(serializedDelegation) {
+    if (Buffer.byteLength(serializedDelegation) > MAX_CALLBACK_BYTES) {
+      throw new NativeGrantValidationError("rejected");
+    }
+    const identity = await this.#loadNativeServiceKey();
+    const activated = await this.#activateNativeDelegation(serializedDelegation, identity);
+    const { ownerDid, spaceId, permissions, expiresAt } = activated;
+    return this.#withNativeGrantLock(ownerDid, async () => {
+      const stateRoot = this.nativeTenantStateRoot(ownerDid);
+      let previous = null;
+      try {
+        const stored = await readJson(this.#nativeGrantPath(stateRoot));
+        if (isRecord(stored) && stored.version === 1 && stored.ownerDid === ownerDid && typeof stored.serviceDid === "string" && samePrincipal(stored.serviceDid, identity.did) && typeof stored.serializedDelegation === "string" && typeof stored.delegationCid === "string" && typeof stored.spaceId === "string" && Array.isArray(stored.permissions) && stored.permissions.every(isPermissionEntry) && nativeOwnerForConnectorGrant(stored.permissions) === ownerDid && typeof stored.expiresAt === "string" && Number.isFinite(Date.parse(stored.expiresAt))) {
+          previous = stored;
+        }
+      } catch (error) {
+        if (!(error instanceof SyntaxError)) throw error;
+      }
+      if (previous !== null) {
+        const previousExpiry = Date.parse(previous.expiresAt);
+        const nextExpiry = expiresAt.getTime();
+        if (previousExpiry > nextExpiry || previousExpiry === nextExpiry && previous.delegationCid !== activated.cid) {
+          throw new NativeGrantValidationError("rejected");
+        }
+        if (previous.delegationCid === activated.cid) {
+          return {
+            ownerDid,
+            serviceDid: normalizeDid(identity.did),
+            expiresAt: previous.expiresAt,
+            stateRoot
+          };
+        }
+      }
+      const session = {
+        delegationHeader: activated.delegation.delegationHeader,
+        delegationCid: activated.cid,
+        spaceId,
+        jwk: identity.jwk,
+        verificationMethod: identity.did,
+        tinycloudHosts: [this.#config.nodeHost]
+      };
+      const grant = {
+        version: 1,
+        ownerDid,
+        serviceDid: normalizeDid(identity.did),
+        serializedDelegation: serializeDelegation(activated.delegation),
+        delegationCid: activated.cid,
+        spaceId,
+        permissions,
+        expiresAt: expiresAt.toISOString()
+      };
+      const sessionPath = this.#sessionPath(stateRoot);
+      const previousSession = await readOptionalText(sessionPath);
+      try {
+        await secureWrite(this.#profilePath(stateRoot), {
+          name: PROFILE,
+          host: this.#config.nodeHost,
+          chainId: activated.delegation.chainId,
+          spaceName: "applications",
+          did: identity.did,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          profile: PROFILE,
+          operatorType: "agent",
+          posture: "delegate-session",
+          ownerDid,
+          sessionDid: identity.did,
+          spaceId,
+          tinycloudHost: this.#config.nodeHost
+        });
+        await secureWrite(this.#keyPath(stateRoot), identity.jwk);
+        await secureWrite(sessionPath, session);
+        const request = await withTinyCloudStateRoot(stateRoot, () => createOrReusePermissionRequest({
+          profile: PROFILE,
+          posture: "delegate-session",
+          operatorType: "agent",
+          host: this.#config.nodeHost,
+          sessionDid: identity.did,
+          ownerDid,
+          spaceId,
+          missing: permissions,
+          granted: [],
+          replace: true
+        }));
+        if (request.status !== "created") {
+          throw new NativeGrantValidationError("native_grant_validation_unavailable");
+        }
+        const imported = await invokeOperation(
+          "tinycloud.auth.import",
+          1,
+          { profile: PROFILE, stateRoot },
+          {
+            kind: "tinycloud.auth.delegation",
+            version: 1,
+            requestId: request.request.requestId,
+            delegationCid: activated.cid,
+            delegation: activated.delegation
+          }
+        );
+        if (imported.status === "error") {
+          throw new NativeGrantValidationError(
+            NATIVE_GRANT_IMPORT_REJECTION_CODES.has(imported.error.code) ? "native_grant_rejected" : "native_grant_validation_unavailable"
+          );
+        }
+        if (imported.status !== "ok" || !isRecord(imported.output) || imported.output.activated !== true || imported.output.cid !== activated.cid) {
+          throw new NativeGrantValidationError("native_grant_validation_unavailable");
+        }
+        await secureWrite(this.#nativeGrantPath(stateRoot), grant);
+      } catch (error) {
+        try {
+          await restoreOptionalText(sessionPath, previousSession);
+        } catch {
+          await rm(this.#nativeGrantPath(stateRoot), { force: true }).catch(() => void 0);
+          throw new NativeGrantValidationError("native_grant_validation_unavailable");
+        }
+        throw error;
+      }
+      return { ownerDid, serviceDid: normalizeDid(identity.did), expiresAt: grant.expiresAt, stateRoot };
+    });
+  }
+  async nativeGrantForOwner(ownerDid) {
+    const canonical = canonicalOwnerDid(ownerDid);
+    if (canonical === void 0) return { status: "rejected" };
+    const stateRoot = this.nativeTenantStateRoot(canonical);
+    let stored;
+    try {
+      stored = await readJson(this.#nativeGrantPath(stateRoot));
+    } catch {
+      return { status: "rejected" };
+    }
+    if (stored === null) return { status: "required" };
+    if (!isRecord(stored) || stored.version !== 1 || stored.ownerDid !== canonical || typeof stored.serviceDid !== "string" || typeof stored.serializedDelegation !== "string" || typeof stored.delegationCid !== "string" || typeof stored.spaceId !== "string" || typeof stored.expiresAt !== "string" || !Array.isArray(stored.permissions) || !stored.permissions.every(isPermissionEntry) || nativeOwnerForConnectorGrant(stored.permissions) !== canonical) {
+      return { status: "rejected" };
+    }
+    const expires = Date.parse(stored.expiresAt);
+    if (!Number.isFinite(expires)) return { status: "rejected" };
+    if (expires <= Date.now()) return { status: "expired" };
+    try {
+      const identity = await this.#loadNativeServiceKey();
+      if (!samePrincipal(stored.serviceDid, identity.did)) return { status: "rejected" };
+      const activated = await this.#activateNativeDelegation(stored.serializedDelegation, identity);
+      if (activated.ownerDid !== canonical || activated.cid !== stored.delegationCid || activated.spaceId !== stored.spaceId || JSON.stringify(activated.permissions) !== JSON.stringify(stored.permissions) || activated.expiresAt.toISOString() !== stored.expiresAt) return { status: "rejected" };
+      return { status: "ok", ownerDid: canonical, stateRoot, expiresAt: stored.expiresAt };
+    } catch (error) {
+      if (error instanceof NativeGrantValidationError) {
+        return { status: error.code === "native_grant_expired" ? "expired" : error.code === "native_grant_validation_unavailable" ? "unavailable" : "rejected" };
+      }
+      return { status: "unavailable" };
+    }
+  }
+  async assertNativeGrantActive(ownerDid) {
+    const canonical = canonicalOwnerDid(ownerDid);
+    if (canonical === void 0) throw new NativeGrantValidationError("rejected");
+    const stateRoot = this.nativeTenantStateRoot(canonical);
+    let stored;
+    try {
+      stored = await readJson(this.#nativeGrantPath(stateRoot));
+    } catch {
+      throw new NativeGrantValidationError("rejected");
+    }
+    if (stored === null) throw new NativeGrantValidationError("required");
+    if (!isRecord(stored) || stored.version !== 1 || stored.ownerDid !== canonical || typeof stored.expiresAt !== "string" || !Number.isFinite(Date.parse(stored.expiresAt))) {
+      throw new NativeGrantValidationError("rejected");
+    }
+    if (Date.parse(stored.expiresAt) <= Date.now()) throw new NativeGrantValidationError("expired");
+  }
   tenantStateRoot(subject) {
     return join(this.#config.stateDir, "tenants", this.#tenantId(subject));
   }
@@ -746,7 +1160,7 @@ var RemoteTenantStore = class {
     const expected = this.#signState(tenantId, nonce);
     const supplied = Buffer.from(signature, "base64url");
     const expectedBytes = Buffer.from(expected, "base64url");
-    if (supplied.length !== expectedBytes.length || !timingSafeEqual(supplied, expectedBytes)) {
+    if (supplied.length !== expectedBytes.length || !timingSafeEqual2(supplied, expectedBytes)) {
       throw new ApprovalRequestError("state_invalid", "Approval state is invalid.");
     }
     const stateRoot = join(this.#config.stateDir, "tenants", tenantId);
@@ -797,6 +1211,123 @@ var RemoteTenantStore = class {
     url.searchParams.set("state", `${pending.tenantId}.${pending.nonce}.${this.#signState(pending.tenantId, pending.nonce)}`);
     return url.toString();
   }
+  async #withNativeGrantLock(ownerDid, action) {
+    const previous = this.#nativeGrantQueues.get(ownerDid) ?? Promise.resolve();
+    let releaseNext;
+    const next = new Promise((resolve2) => {
+      releaseNext = resolve2;
+    });
+    this.#nativeGrantQueues.set(ownerDid, next);
+    await previous;
+    try {
+      return await action();
+    } finally {
+      releaseNext();
+      if (this.#nativeGrantQueues.get(ownerDid) === next) this.#nativeGrantQueues.delete(ownerDid);
+    }
+  }
+  async #loadNativeServiceKey() {
+    if (this.#nativeIdentity === void 0) {
+      const loading = this.#readOrCreateNativeServiceKey();
+      this.#nativeIdentity = loading;
+      void loading.catch(() => {
+        if (this.#nativeIdentity === loading) this.#nativeIdentity = void 0;
+      });
+    }
+    return this.#nativeIdentity;
+  }
+  async #readOrCreateNativeServiceKey() {
+    const path = join(this.#config.stateDir, ".tinycloud", "native-service-key.json");
+    await secureDirectory(dirname(path));
+    let stored = await readJson(path);
+    if (stored === null) {
+      const generated = generateSessionKey();
+      try {
+        await writeFile(path, `${JSON.stringify({ version: 1, jwk: generated.jwk })}
+`, {
+          mode: 384,
+          flag: "wx"
+        });
+      } catch (error) {
+        if (!isRecord(error) || error.code !== "EEXIST") throw error;
+      }
+      await chmod(path, 384);
+      stored = await readJson(path);
+    }
+    if (stored === null || !isRecord(stored) || stored.version !== 1 || !isRecord(stored.jwk)) {
+      throw new Error("The native MCP service identity is unavailable.");
+    }
+    return { did: didFromJwk(stored.jwk), jwk: stored.jwk };
+  }
+  async #activateNativeDelegation(serialized, identity) {
+    let delegation;
+    try {
+      const parsed = JSON.parse(serialized);
+      if (!isRecord(parsed)) throw new Error("invalid delegation");
+      delegation = deserializeDelegation(serialized);
+    } catch {
+      throw new NativeGrantValidationError("native_grant_rejected");
+    }
+    if (!isRecord(delegation.delegationHeader) || typeof delegation.delegationHeader.Authorization !== "string" || delegation.delegationHeader.Authorization.length === 0 || typeof delegation.cid !== "string" || delegation.cid.length === 0 || typeof delegation.delegateDID !== "string" || !samePrincipal(delegation.delegateDID, normalizeDid(identity.did)) || typeof delegation.spaceId !== "string" || typeof delegation.ownerAddress !== "string" || !Number.isSafeInteger(delegation.chainId) || typeof delegation.host !== "string" || !sameNodeHost(delegation.host, this.#config.nodeHost) || !(delegation.expiry instanceof Date) || !Number.isFinite(delegation.expiry.getTime())) {
+      throw new NativeGrantValidationError("native_grant_rejected");
+    }
+    const now = Date.now();
+    const claimedExpiry = delegation.expiry.getTime();
+    if (claimedExpiry <= now) throw new NativeGrantValidationError("native_grant_expired");
+    if (claimedExpiry > now + NATIVE_GRANT_MAX_LIFETIME_SECONDS * 1e3) {
+      throw new NativeGrantValidationError("native_grant_rejected");
+    }
+    let ownerDid;
+    let spaceId;
+    const node = new TinyCloudNode({ host: this.#config.nodeHost });
+    try {
+      await node.restoreSession({
+        delegationHeader: delegation.delegationHeader,
+        delegationCid: delegation.cid,
+        spaceId: delegation.spaceId,
+        jwk: identity.jwk,
+        verificationMethod: identity.did,
+        tinycloudHosts: [this.#config.nodeHost]
+      });
+      const activated = await activateValidatedRuntimeDelegation(node, delegation, {
+        host: this.#config.nodeHost,
+        authorize: (permissions) => {
+          const derivedOwner = nativeOwnerForConnectorGrant(permissions);
+          const signedSpace = permissions[0]?.space;
+          if (derivedOwner === void 0 || signedSpace === void 0) return false;
+          const metadataOwner = canonicalOwnerDid(
+            `did:pkh:eip155:${delegation.chainId}:${delegation.ownerAddress}`
+          );
+          if (metadataOwner !== derivedOwner || delegation.spaceId.toLowerCase() !== signedSpace.toLowerCase()) return false;
+          ownerDid = derivedOwner;
+          spaceId = signedSpace;
+          return true;
+        }
+      });
+      if (ownerDid === void 0 || spaceId === void 0 || !samePrincipal(activated.audience, normalizeDid(identity.did)) || activated.expiry.getTime() > now + NATIVE_GRANT_MAX_LIFETIME_SECONDS * 1e3) {
+        throw new NativeGrantValidationError("native_grant_rejected");
+      }
+      return {
+        ownerDid,
+        spaceId,
+        permissions: [...activated.effectivePermissions],
+        cid: activated.cid,
+        expiresAt: activated.expiry,
+        delegation: activated.delegation
+      };
+    } catch (error) {
+      if (error instanceof NativeGrantValidationError) throw error;
+      if (error instanceof RuntimeDelegationRejectedError) {
+        throw new NativeGrantValidationError(
+          error.reason === "expired" ? "native_grant_expired" : error.reason === "activation_unavailable" ? "native_grant_validation_unavailable" : "native_grant_rejected"
+        );
+      }
+      throw new NativeGrantValidationError("native_grant_validation_unavailable");
+    }
+  }
+  #nativeGrantPath(stateRoot) {
+    return join(stateRoot, ".tinycloud", "native-grant.json");
+  }
   #tenantId(subject) {
     return createHmac("sha256", this.#config.stateSecret).update(`tenant:${subject}`).digest("hex");
   }
@@ -890,6 +1421,21 @@ function samePrincipal(left, right) {
 function normalizeDid(value) {
   return value.split("#", 1)[0];
 }
+function sameNodeHost(left, right) {
+  try {
+    const normalize = (value) => {
+      const url = new URL(value);
+      if (url.username !== "" || url.password !== "") return "";
+      url.hash = "";
+      url.search = "";
+      url.pathname = url.pathname.replace(/\/+$/, "");
+      return url.toString().replace(/\/+$/, "");
+    };
+    return normalize(left) !== "" && normalize(left) === normalize(right);
+  } catch {
+    return false;
+  }
+}
 function isPermissionEntry(value) {
   return isRecord(value) && typeof value.service === "string" && typeof value.space === "string" && typeof value.path === "string" && Array.isArray(value.actions) && value.actions.every((action) => typeof action === "string");
 }
@@ -920,6 +1466,23 @@ async function readJson(path) {
     throw error;
   }
 }
+async function readOptionalText(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (isRecord(error) && error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function restoreOptionalText(path, contents) {
+  if (contents === null) {
+    await rm(path, { force: true });
+    return;
+  }
+  await secureDirectory(dirname(path));
+  await writeFile(path, contents, { mode: 384 });
+  await chmod(path, 384);
+}
 async function reusablePending(directory, expected) {
   let names;
   try {
@@ -1316,7 +1879,7 @@ function createJsonSchemaValidator() {
   return new AjvJsonSchemaValidator();
 }
 function registerTinyCloudTools(server, selection, validator) {
-  const bindings = TOOL_BINDINGS.filter((binding) => bindingSurfaces(binding).includes(selection.surface));
+  const bindings = TOOL_BINDINGS.filter((binding) => bindingSurfaces(binding).includes(selection.surface) && (selection.allowedTools === void 0 || selection.allowedTools.includes(binding.name)));
   for (const binding of bindings) {
     const operation = definitions.get(`${binding.operationId}@${binding.operationVersion}`);
     if (operation === void 0) {
@@ -1394,7 +1957,7 @@ function outcomeCode(result) {
 // package.json
 var package_default = {
   name: "@tinycloud/mcp",
-  version: "0.8.3-beta.2",
+  version: "0.8.3-beta.20",
   description: "TinyCloud delegated operations MCP server",
   keywords: [
     "tinycloud",
@@ -1465,9 +2028,9 @@ var package_default = {
   dependencies: {
     "@modelcontextprotocol/node": "2.0.0-beta.5",
     "@modelcontextprotocol/server": "2.0.0-beta.5",
-    "@tinycloud/node-sdk": "3.8.0-beta.2",
+    "@tinycloud/node-sdk": "3.8.0-beta.18",
     "@tinycloud/node-sdk-wasm": "1.7.8",
-    "@tinycloud/operations": "0.7.7-beta.2",
+    "@tinycloud/operations": "0.7.7-beta.17",
     jose: "6.2.4"
   },
   devDependencies: {
@@ -1491,15 +2054,22 @@ var MCP_SERVER_NAME = "tinycloud-mcp";
 
 // src/http.ts
 var REQUIRED_SCOPE = "tinycloud:mcp";
+var LOCAL_CLI_PACKAGE = ["@tinycloud", "cli"].join("/");
+var LOCAL_MCP_PACKAGE = ["@tinycloud", "mcp"].join("/");
 function createHostedMcpApp(config) {
+  if (config.nativeServiceCredential !== void 0 && Buffer.byteLength(config.nativeServiceCredential, "utf8") < 32) {
+    throw new Error("TC_MCP_NATIVE_SERVICE_CREDENTIAL must contain at least 32 bytes.");
+  }
   const resourceUrl = canonicalResourceUrl(config.publicUrl);
   const pluginUrl = new URL("./chatgpt/mcp", resourceUrl);
-  const hosted = createHostedSurface(config, resourceUrl, "hosted");
+  const statusFor = (resource) => config.introspection === void 0 ? void 0 : createTokenStatusChecker({ ...config.introspection, resourceUrl: resource.toString() });
+  const hosted = createHostedSurface(config, resourceUrl, "hosted", statusFor(resourceUrl));
   const plugin = createHostedSurface({
     ...config,
+    nativeServiceCredential: void 0,
     stateDir: join3(config.stateDir, "chatgpt"),
     approvalPath: new URL("./connect", pluginUrl).pathname
-  }, pluginUrl, "public");
+  }, pluginUrl, "public", statusFor(pluginUrl));
   const pluginPaths = {
     [pluginUrl.pathname]: true,
     [new URL("./connect", pluginUrl).pathname]: true,
@@ -1513,7 +2083,7 @@ function createHostedMcpApp(config) {
     }
   };
 }
-function createHostedSurface(config, resourceUrl, surface) {
+function createHostedSurface(config, resourceUrl, surface, tokenStatus) {
   const connectPath = config.approvalPath ?? "/connect";
   const callbackPath = `${connectPath}/callback`;
   const issuer = String(config.oauthMetadata.issuer);
@@ -1522,7 +2092,8 @@ function createHostedSurface(config, resourceUrl, surface) {
     issuer,
     audience: resourceUrl.toString(),
     jwksUri,
-    requiredScope: REQUIRED_SCOPE
+    requiredScope: REQUIRED_SCOPE,
+    ...tokenStatus === void 0 ? {} : { tokenStatus }
   });
   const resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(resourceUrl);
   const authenticate = requireBearerAuth({
@@ -1531,16 +2102,19 @@ function createHostedSurface(config, resourceUrl, surface) {
     resourceMetadataUrl
   });
   const store = new RemoteTenantStore({ ...config, publicUrl: resourceUrl });
+  const nativeServiceIdentityEnabled = surface === "hosted" && config.nativeServiceCredential !== void 0;
+  if (nativeServiceIdentityEnabled) void store.nativeServiceIdentity().catch(() => void 0);
   const handler = createMcpHandler(async ({ authInfo: authInfo2 }) => {
-    const identity = oauthIdentity(authInfo2);
+    const nativeOwner = typeof authInfo2?.extra?.nativeOwnerDid === "string" ? authInfo2.extra.nativeOwnerDid : void 0;
+    const identity = nativeOwner === void 0 ? oauthIdentity(authInfo2) : { subject: `native:${nativeOwner}`, ownerDids: [nativeOwner] };
     const { subject, ownerDids } = identity;
-    const stateRoot = await store.initializeTenant(subject);
+    const stateRoot = nativeOwner === void 0 ? await store.initializeTenant(subject) : store.nativeTenantStateRoot(nativeOwner);
     const validator = createJsonSchemaValidator();
     const server = new McpServer2(
       { name: MCP_SERVER_NAME, version: MCP_VERSION },
       {
         jsonSchemaValidator: validator,
-        instructions: surface === "public" ? "Use TinyCloud only for the user's requested task. Call tinycloud_connect first. If an operation returns authority_required, present approval.url and wait for the user's approval before retrying. If approval is declined, stop that operation. For personal records, call tinycloud_apps_context first. Never request or store passwords, API keys, authentication codes, government identifiers, payment-card data, or protected health information." : "Call tinycloud_connect first. If an operation returns authority_required, open approval.url, then retry that operation unchanged. For personal records such as weight, workouts, goals or todos, call tinycloud_apps_context first."
+        instructions: nativeOwner === void 0 ? surface === "public" ? "Use TinyCloud only for the user's requested task. Call tinycloud_connect first. If an operation returns authority_required, present approval.url and wait for the user's approval before retrying. If approval is declined, stop that operation. For personal records, call tinycloud_apps_context first. Never request or store passwords, API keys, authentication codes, government identifiers, payment-card data, or protected health information." : "Call tinycloud_connect first. If an operation returns authority_required, open approval.url, then retry that operation unchanged. For personal records such as weight, workouts, goals or todos, call tinycloud_apps_context first." : "Use only the user's requested connector-transcript data. The signed TinyCloud grant authorizes read-only SQL and transcript KV reads."
       }
     );
     registerTinyCloudTools(server, {
@@ -1549,10 +2123,15 @@ function createHostedSurface(config, resourceUrl, surface) {
       explicitProfile: true,
       allowOwnerProfile: false,
       stateRoot,
-      beforeOperation: () => store.validateTenant(subject, ownerDids),
-      transformOperationResult: (result, invocation) => store.decorateAuthorityResult(subject, ownerDids, result, invocation)
+      ...nativeOwner === void 0 ? {} : {
+        allowedTools: ["tinycloud_sql_query", "tinycloud_kv_get"]
+      },
+      beforeOperation: nativeOwner === void 0 ? () => store.validateTenant(subject, ownerDids) : () => store.assertNativeGrantActive(nativeOwner),
+      ...nativeOwner === void 0 ? {
+        transformOperationResult: (result, invocation) => store.decorateAuthorityResult(subject, ownerDids, result, invocation)
+      } : {}
     }, validator);
-    registerConnectTool(server, validator, store, identity, surface);
+    if (nativeOwner === void 0) registerConnectTool(server, validator, store, identity, surface);
     return server;
   }, {
     legacy: "stateless",
@@ -1568,14 +2147,205 @@ function createHostedSurface(config, resourceUrl, surface) {
   const allowedHosts = [resourceUrl.hostname];
   return {
     async fetch(request) {
-      const metadata = oauthMetadataResponse(request, metadataOptions);
-      if (metadata !== void 0) return metadata;
       const url = new URL(request.url);
+      if (url.pathname !== "/healthz") {
+        const hostFailure = hostHeaderValidationResponse(request, allowedHosts);
+        if (hostFailure !== void 0) return hostFailure;
+      }
+      if (url.pathname === "/.well-known/oauth-protected-resource" && surface === "hosted") {
+        const metadataUrl = new URL(getOAuthProtectedResourceMetadataUrl(resourceUrl));
+        const metadataRequest = new Request(metadataUrl.toString(), {
+          method: request.method,
+          headers: request.headers
+        });
+        const response = oauthMetadataResponse(metadataRequest, metadataOptions);
+        if (response !== void 0) return withBearerMethodsSupported(response);
+      }
+      const metadata = oauthMetadataResponse(request, metadataOptions);
+      if (metadata !== void 0) {
+        return surface === "hosted" ? withBearerMethodsSupported(metadata) : metadata;
+      }
+      if (url.pathname === "/.well-known/ai-catalog.json" && surface === "hosted") {
+        if (request.method === "OPTIONS") {
+          return publicMetadataCors(new Response(null, { status: 204 }), request);
+        }
+        if (request.method !== "GET") return methodNotAllowed("GET");
+        return publicMetadataCors(Response.json({
+          specVersion: "1.0",
+          host: {
+            displayName: "TinyCloud, Inc.",
+            identifier: "https://mcp.tinycloud.xyz",
+            documentationUrl: "https://docs.tinycloud.xyz/cli/mcp"
+          },
+          entries: [{
+            identifier: "urn:air:tinycloud.xyz:mcp:tinycloud-mcp",
+            displayName: "TinyCloud MCP",
+            type: "application/json",
+            description: "Hosted Streamable HTTP MCP server for delegated TinyCloud operations.",
+            url: new URL("/.well-known/mcp/server-card.json", resourceUrl).toString(),
+            representativeQueries: [
+              "How do I connect to TinyCloud's hosted MCP server?",
+              "Which endpoint provides TinyCloud's delegated MCP operations?",
+              "How can I connect to TinyCloud MCP using local stdio?"
+            ]
+          }]
+        }, {
+          headers: {
+            "cache-control": "public, max-age=300",
+            "content-type": "application/json; charset=utf-8"
+          }
+        }), request);
+      }
+      if (url.pathname === "/.well-known/poppy.json" && surface === "hosted") {
+        if (request.method === "OPTIONS") {
+          return publicMetadataCors(new Response(null, { status: 204 }), request);
+        }
+        if (request.method !== "GET") return methodNotAllowed("GET");
+        return publicMetadataCors(Response.json({
+          protocol_version: "0.1",
+          organization: {
+            name: "TinyCloud, Inc.",
+            domain: resourceUrl.hostname
+          },
+          web: {}
+        }, {
+          headers: {
+            "cache-control": "public, max-age=300",
+            "content-type": "application/json; charset=utf-8"
+          }
+        }), request);
+      }
+      if (url.pathname === "/auth.md" && surface === "hosted") {
+        if (request.method === "OPTIONS") {
+          return publicMetadataCors(new Response(null, { status: 204 }), request);
+        }
+        if (request.method !== "GET") return methodNotAllowed("GET");
+        const issuerUrl = new URL(issuer);
+        const authorizationServerMetadataUrl = new URL(
+          `/.well-known/oauth-authorization-server${issuerUrl.pathname}`,
+          issuerUrl.origin
+        );
+        const registrationEndpoint = config.oauthMetadata.registration_endpoint;
+        const registrationNote = typeof registrationEndpoint === "string" ? `OpenKey's OAuth \`registration_endpoint\` is ${registrationEndpoint}; it registers OAuth clients, not TinyCloud users or agents.` : "The authorization server does not advertise an OAuth client registration endpoint.";
+        const authDoc = [
+          "# TinyCloud MCP auth.md",
+          "",
+          `Protected resource: ${resourceUrl}.`,
+          "",
+          "Send an OAuth access token in the `Authorization: Bearer` header.",
+          "",
+          `Protected Resource Metadata: ${new URL("/.well-known/oauth-protected-resource", resourceUrl)}.`,
+          `Authorization server issuer: ${issuer}.`,
+          `Authorization server metadata: ${authorizationServerMetadataUrl}.`,
+          `Scope: \`${REQUIRED_SCOPE}\`.`,
+          "",
+          "Hosted access uses OpenKey OAuth.",
+          registrationNote,
+          "TinyCloud does not host an Auth.md agent-enrollment or user-registration endpoint for this service.",
+          "No `agent_auth` registration block is published because no agent-registration endpoint is available.",
+          "",
+          `Local stdio is a separate option configured with \`${LOCAL_CLI_PACKAGE}\` and \`${LOCAL_MCP_PACKAGE}\`.`,
+          "",
+          "Connection steps: https://docs.tinycloud.xyz/cli/mcp"
+        ].join("\n") + "\n";
+        return publicMetadataCors(publicText(authDoc, "text/markdown; charset=utf-8"), request);
+      }
+      if (url.pathname === "/robots.txt" && surface === "hosted") {
+        return request.method === "GET" ? publicText(`User-agent: *
+Allow: /
+Sitemap: ${new URL("/sitemap.xml", resourceUrl)}
+Agentmap: ${new URL("/.well-known/ai-catalog.json", resourceUrl)}
+`, "text/plain; charset=utf-8") : methodNotAllowed("GET");
+      }
+      if ((url.pathname === "/mcp/server-card" || url.pathname === "/.well-known/mcp/server-card.json") && surface === "hosted") {
+        if (request.method === "OPTIONS") {
+          return publicMetadataCors(new Response(null, { status: 204 }), request);
+        }
+        if (request.method !== "GET") return methodNotAllowed("GET");
+        const identity = nativeServiceIdentityEnabled ? await store.nativeServiceIdentity().catch(() => void 0) : void 0;
+        const card = {
+          $schema: "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
+          name: `xyz.tinycloud/${MCP_SERVER_NAME}`,
+          title: "TinyCloud MCP",
+          version: MCP_VERSION,
+          description: "MCP server for delegated TinyCloud operations.",
+          websiteUrl: "https://docs.tinycloud.xyz/cli/mcp",
+          repository: { source: "github", url: "https://github.com/TinyCloudLabs/js-sdk", subfolder: "packages/mcp" },
+          remotes: [{ type: "streamable-http", url: resourceUrl.toString() }]
+        };
+        if (identity !== void 0) {
+          card["x-tinycloud-native-auth"] = {
+            serviceDid: identity.serviceDid,
+            serviceDidField: "x-tinycloud-native-auth.serviceDid",
+            grantEndpoint: {
+              method: "POST",
+              path: "/native/grant",
+              body: { delegation: "serialized PortableDelegation JSON string" }
+            },
+            serviceCredentialHeader: NATIVE_SERVICE_CREDENTIAL_HEADER,
+            serviceCredentialEnv: "TC_MCP_NATIVE_SERVICE_CREDENTIAL",
+            ownerDidHeader: NATIVE_OWNER_DID_HEADER,
+            maxGrantLifetimeSeconds: NATIVE_GRANT_MAX_LIFETIME_SECONDS,
+            acceptedCapabilities: [
+              { service: "tinycloud.sql", space: "applications", path: "xyz.tinycloud.tinychat/connectors", actions: ["tinycloud.sql/read"] },
+              { service: "tinycloud.kv", space: "applications", path: "xyz.tinycloud.tinychat/connectors/", actions: ["tinycloud.kv/get", "tinycloud.kv/list"] }
+            ],
+            tools: ["tinycloud_sql_query", "tinycloud_kv_get"],
+            errors: {
+              required: NATIVE_GRANT_REQUIRED,
+              expired: NATIVE_GRANT_EXPIRED,
+              rejected: NATIVE_GRANT_REJECTED,
+              serviceUnauthorized: NATIVE_SERVICE_UNAUTHORIZED,
+              serviceUnavailable: NATIVE_SERVICE_UNAVAILABLE,
+              validationUnavailable: NATIVE_GRANT_VALIDATION_UNAVAILABLE
+            }
+          };
+        }
+        return publicMetadataCors(Response.json(card, {
+          headers: { "cache-control": "public, max-age=300" }
+        }), request);
+      }
+      if (url.pathname === "/llms.txt" && surface === "hosted") {
+        return request.method === "GET" ? publicText(`# TinyCloud MCP
+
+Hosted Streamable HTTP endpoint: https://mcp.tinycloud.xyz/mcp (OpenKey OAuth).
+
+Connection documentation: https://docs.tinycloud.xyz/cli/mcp
+
+Local alternative: install ${LOCAL_CLI_PACKAGE} and ${LOCAL_MCP_PACKAGE}, then set up tinycloud-mcp as a stdio server in your MCP client.
+`, "text/plain; charset=utf-8") : methodNotAllowed("GET");
+      }
+      if (url.pathname === "/sitemap.xml" && surface === "hosted") {
+        const sitemap = `<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url><loc>${new URL("/", resourceUrl)}</loc></url></urlset>`;
+        return request.method === "GET" ? publicText(sitemap, "application/xml; charset=utf-8") : methodNotAllowed("GET");
+      }
+      if (url.pathname === "/" && surface === "hosted") {
+        if (request.method !== "GET" && request.method !== "HEAD") return methodNotAllowed("GET, HEAD");
+        const markdown = request.headers.get("accept")?.includes("text/markdown") ?? false;
+        const content = markdown ? `# TinyCloud MCP
+
+Hosted endpoint: <https://mcp.tinycloud.xyz/mcp> (Streamable HTTP, OpenKey OAuth).
+
+[Connection documentation](https://docs.tinycloud.xyz/cli/mcp).
+
+Local alternative: install \`${LOCAL_CLI_PACKAGE}\` and \`${LOCAL_MCP_PACKAGE}\` and connect the \`tinycloud-mcp\` stdio server.
+` : `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="ai-catalog" href="/.well-known/ai-catalog.json"><title>TinyCloud MCP</title></head><main><h1>TinyCloud MCP</h1><p>Hosted MCP endpoint: <code>https://mcp.tinycloud.xyz/mcp</code> (Streamable HTTP, OpenKey OAuth).</p><p><a href="https://docs.tinycloud.xyz/cli/mcp">Connection documentation</a></p><p>Local alternative: install <code>${LOCAL_CLI_PACKAGE}</code> and <code>${LOCAL_MCP_PACKAGE}</code> and connect the <code>tinycloud-mcp</code> stdio server.</p></main></html>`;
+        const headers = new Headers({
+          "content-type": markdown ? "text/markdown; charset=utf-8" : "text/html; charset=utf-8",
+          "cache-control": "public, max-age=300",
+          "content-security-policy": "default-src 'none'; base-uri 'none'; frame-ancestors 'none'",
+          "x-content-type-options": "nosniff",
+          vary: "Accept"
+        });
+        headers.set(
+          "link",
+          `<${new URL("/mcp/server-card", resourceUrl)}>; rel="describedby"; type="application/json", <https://docs.tinycloud.xyz/cli/mcp>; rel="service-doc"`
+        );
+        return new Response(request.method === "HEAD" ? null : content, { headers });
+      }
       if (url.pathname === "/healthz") {
         return request.method === "GET" ? json({ ok: true }) : methodNotAllowed("GET");
       }
-      const hostFailure = hostHeaderValidationResponse(request, allowedHosts);
-      if (hostFailure !== void 0) return hostFailure;
       if (url.pathname === connectPath) {
         if (request.method !== "GET") return methodNotAllowed("GET");
         try {
@@ -1631,6 +2401,73 @@ function createHostedSurface(config, resourceUrl, surface) {
           );
         }
       }
+      if (url.pathname === "/native/grant" && surface === "hosted") {
+        if (request.method !== "POST") return methodNotAllowed("POST");
+        if (request.headers.has("origin")) return json({ error: NATIVE_SERVICE_UNAUTHORIZED }, 403);
+        if (config.nativeServiceCredential === void 0) {
+          return json({ error: NATIVE_SERVICE_UNAVAILABLE }, 503);
+        }
+        if (!serviceCredentialMatches(
+          request.headers.get(NATIVE_SERVICE_CREDENTIAL_HEADER),
+          config.nativeServiceCredential
+        )) return json({ error: NATIVE_SERVICE_UNAUTHORIZED }, 403);
+        if (!request.headers.get("content-type")?.toLowerCase().startsWith("application/json")) {
+          return json({ error: NATIVE_GRANT_REJECTED }, 401);
+        }
+        const bodyText = await readBoundedBodyText(request, MAX_NATIVE_GRANT_BODY_BYTES);
+        if (bodyText === void 0) return json({ error: NATIVE_GRANT_REJECTED }, 401);
+        let body;
+        try {
+          body = JSON.parse(bodyText);
+        } catch {
+          return json({ error: NATIVE_GRANT_REJECTED }, 401);
+        }
+        if (typeof body !== "object" || body === null || Array.isArray(body) || !("delegation" in body)) {
+          return json({ error: NATIVE_GRANT_REJECTED }, 401);
+        }
+        const grantBody = body;
+        if (Object.keys(body).length !== 1 || typeof grantBody.delegation !== "string") {
+          return json({ error: NATIVE_GRANT_REJECTED }, 401);
+        }
+        try {
+          const accepted = await store.acceptNativeGrant(grantBody.delegation);
+          return json({
+            ownerDid: accepted.ownerDid,
+            serviceDid: accepted.serviceDid,
+            expiresAt: accepted.expiresAt
+          }, 201);
+        } catch (error) {
+          return nativeGrantErrorResponse(error);
+        }
+      }
+      if (url.pathname === resourceUrl.pathname && surface === "hosted" && (request.headers.has(NATIVE_SERVICE_CREDENTIAL_HEADER) || request.headers.has(NATIVE_OWNER_DID_HEADER))) {
+        if (config.nativeServiceCredential === void 0) {
+          return json({ error: NATIVE_SERVICE_UNAVAILABLE }, 503);
+        }
+        if (!serviceCredentialMatches(
+          request.headers.get(NATIVE_SERVICE_CREDENTIAL_HEADER),
+          config.nativeServiceCredential
+        )) return json({ error: NATIVE_SERVICE_UNAUTHORIZED }, 403);
+        if (request.headers.has("origin")) return json({ error: NATIVE_SERVICE_UNAUTHORIZED }, 403);
+        const ownerHeader = request.headers.get(NATIVE_OWNER_DID_HEADER);
+        if (ownerHeader === null || ownerHeader.length === 0) {
+          return json({ error: NATIVE_GRANT_REQUIRED }, 401);
+        }
+        const grant = await store.nativeGrantForOwner(ownerHeader);
+        if (grant.status !== "ok") {
+          const status = grant.status === "unavailable" ? 503 : 401;
+          const code = grant.status === "required" ? NATIVE_GRANT_REQUIRED : grant.status === "expired" ? NATIVE_GRANT_EXPIRED : grant.status === "unavailable" ? NATIVE_GRANT_VALIDATION_UNAVAILABLE : NATIVE_GRANT_REJECTED;
+          return json({ error: code }, status);
+        }
+        return handler.fetch(request, {
+          authInfo: {
+            token: "native-service",
+            clientId: "tinycloud-native",
+            scopes: [],
+            extra: { nativeOwnerDid: grant.ownerDid }
+          }
+        });
+      }
       if (url.pathname !== resourceUrl.pathname) return json({ error: "Not found" }, 404);
       const originFailure = validateOrigin(request, config.allowedOrigins);
       if (originFailure !== void 0) return originFailure;
@@ -1742,9 +2579,77 @@ function callbackCors(response, openkeyHost) {
   headers.set("vary", "Origin");
   return new Response(response.body, { status: response.status, headers });
 }
+async function readBoundedBodyText(request, maxBytes) {
+  const contentLength = request.headers.get("content-length");
+  if (contentLength !== null) {
+    const parsedLength = Number(contentLength);
+    if (Number.isFinite(parsedLength) && parsedLength > maxBytes) return void 0;
+  }
+  if (request.body === null) return "";
+  const reader = request.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel();
+        return void 0;
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
+}
+function nativeGrantErrorResponse(error) {
+  if (!(error instanceof NativeGrantValidationError)) {
+    return json({ error: NATIVE_SERVICE_UNAVAILABLE }, 503);
+  }
+  const unavailable = error.code === NATIVE_GRANT_VALIDATION_UNAVAILABLE || error.code === NATIVE_SERVICE_UNAVAILABLE;
+  return json({ error: error.code }, unavailable ? 503 : 401);
+}
 function json(value, status = 200) {
   return Response.json(value, { status, headers: { "cache-control": "no-store" } });
 }
+async function withBearerMethodsSupported(response) {
+  if (response.status === 204 || response.body === null) return response;
+  const metadata = await response.json();
+  const headers = new Headers(response.headers);
+  headers.delete("content-length");
+  headers.delete("content-encoding");
+  return new Response(JSON.stringify({ ...metadata, bearer_methods_supported: ["header"] }), {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+function publicMetadataCors(response, request) {
+  const headers = new Headers(response.headers);
+  headers.set("access-control-allow-origin", "*");
+  headers.set("access-control-allow-methods", "GET, OPTIONS");
+  const requestedHeaders = request.method === "OPTIONS" ? request.headers.get("access-control-request-headers") : null;
+  if (requestedHeaders !== null) {
+    headers.set("access-control-allow-headers", requestedHeaders);
+  }
+  headers.set(
+    "vary",
+    requestedHeaders === null ? "Origin" : "Origin, Access-Control-Request-Headers"
+  );
+  return new Response(response.body, { status: response.status, headers });
+}
+function publicText(text, contentType) {
+  return new Response(text, {
+    headers: {
+      "content-type": contentType,
+      "cache-control": "public, max-age=300",
+      "x-content-type-options": "nosniff"
+    }
+  });
+}
 function methodNotAllowed(allow) {
   return new Response("Method not allowed", { status: 405, headers: { allow } });
 }
@@ -1774,7 +2679,14 @@ async function main() {
     approvalTtlSeconds: positiveInteger(process.env.TC_MCP_APPROVAL_TTL_SECONDS, 300),
     delegationExpiry: process.env.TC_MCP_DELEGATION_EXPIRY ?? "1h",
     allowedOrigins: commaList(process.env.TC_MCP_ALLOWED_ORIGINS),
-    oauthMetadata
+    ...process.env.TC_MCP_NATIVE_SERVICE_CREDENTIAL === void 0 ? {} : { nativeServiceCredential: process.env.TC_MCP_NATIVE_SERVICE_CREDENTIAL },
+    oauthMetadata,
+    introspection: {
+      endpoint: requiredUrl("TC_MCP_INTROSPECTION_URL").toString(),
+      clientId: requiredString("TC_MCP_INTROSPECTION_CLIENT_ID"),
+      clientSecret: requiredString("TC_MCP_INTROSPECTION_CLIENT_SECRET"),
+      authMethod: introspectionAuthMethod(process.env.TC_MCP_INTROSPECTION_AUTH_METHOD)
+    }
   });
   const nodeHandler = toNodeHandler(app);
   const server = createServer(nodeHandler);
@@ -1807,6 +2719,11 @@ function requiredAbsolutePath(name) {
   if (!isAbsolute(value)) throw new Error(`${name} must be an absolute path.`);
   return resolve(value);
 }
+function introspectionAuthMethod(value) {
+  if (value === void 0 || value === "basic") return "basic";
+  if (value === "post") return "post";
+  throw new Error("TC_MCP_INTROSPECTION_AUTH_METHOD must be basic or post.");
+}
 function positiveInteger(value, fallback) {
   if (value === void 0) return fallback;
   const parsed = Number(value);