@astroscope/airlock 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Simon Bobrov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @astroscope/airlock
+
+Strip excess props from hydrated Astro islands — prevents server data leaking to the client, reduces HTML payload size.
+
+## Why?
+
+When Astro hydrates a framework component with `client:*` directives, **all props are serialized** into the HTML. TypeScript's structural typing allows passing objects with extra properties — those silently leak to the client.
+
+```astro
+---
+const user = await db.getUser(id);
+// user = { name, email, passwordHash, sessionToken, ... }
+---
+
+<!-- passwordHash and sessionToken end up in the page source -->
+<UserCard client:load {...user} />
+```
+
+Airlock uses the component's TypeScript prop types to strip unknown keys before serialization. If `UserCard` declares `{ name: string; email: string }`, only those fields reach the client.
+
+## Installation
+
+```bash
+npm install @astroscope/airlock
+```
+
+## Usage
+
+```ts
+// astro.config.ts
+import { defineConfig } from 'astro/config';
+import airlock from '@astroscope/airlock';
+import react from '@astrojs/react';
+
+export default defineConfig({
+  integrations: [react(), airlock()],
+});
+```
+
+That's it. No changes to your components or templates.
+
+## Important disclaimer
+
+Airlock is **not a silver bullet** — it is an additional layer of defense. Passing sensitive server data to client components is still a bad practice. The best approach is to explicitly map only the fields you need. Airlock catches the cases where that discipline slips.
+
+Example: a component that was correctly stripped can silently break if someone changes its props type to `any` or `Record<string, unknown>` — airlock sees "allow all" and stops stripping. A refactor that widens a type can undo the protection without any visible error. Airlock catches accidental leaks, but it can't protect against type definitions that explicitly opt out of safety.
+
+If hydrated components in your `.astro` source are detected but cannot be matched in the compiled output, **the build will fail**. This is intentional — breaking the build is safer than silently leaking data.
+
+## How it works
+
+Under the hood, airlock generates [Zod](https://zod.dev) schemas from your component's TypeScript types and uses `.parse()` to strip unknown keys at the serialization boundary.
+
+1. **Detects hydrated components** — parses raw `.astro` source using `@astrojs/compiler` to find components with `client:*` directives
+2. **Extracts prop types** — uses the TypeScript compiler API to resolve the component's declared prop types
+3. **Generates Zod schemas** — converts prop types to Zod schema code (e.g. `z.object({ name: z.any(), email: z.any() })`)
+4. **Wraps props in compiled output** — uses Babel to find `renderComponent` calls via scope analysis and wraps their props argument with `schema.parse()`
+5. **Schemas are shared** — a virtual module holds all schemas, so each is created once at runtime regardless of how many pages use the component
+6. **Verifies completeness** — every detected component must be found in the compiled output, otherwise the build fails
+
+### Before (what Astro serializes)
+
+```html
+<astro-island
+  props='{"name":"John","email":"j@test.com","passwordHash":"$2b$10$...","sessionToken":"eyJ..."}'
+></astro-island>
+```
+
+### After (with airlock)
+
+```html
+<astro-island props='{"name":"John","email":"j@test.com"}'></astro-island>
+```
+
+## What it handles
+
+- **Flat objects** — strips top-level excess keys
+- **Nested objects** — recursively strips at every level
+- **Arrays of objects** — strips excess keys from each element
+- **Discriminated unions** — uses `z.discriminatedUnion()` for precise per-variant stripping
+- **Recursive types** — handles self-referencing types via `z.lazy()`
+- **Generic components** — extracts prop shapes from type parameter constraints
+- **All import styles** — default, named, aliased (`import { Card as UserCard }`)
+- **Record / index signatures** — treated as ALLOW_ALL (no stripping)
+
+### When stripping is skipped
+
+Airlock skips stripping entirely for components whose props type intentionally accepts arbitrary keys:
+
+- **Entire props type** is `any`, `unknown`, or `Record<string, unknown>` — no type info to strip with
+- Components with no user props (only `client:*` directives)
+
+Note: individual properties typed as `any` are still kept — only their **keys** matter for stripping. `{ data: any; title: string }` keeps both `data` and `title`, but strips any other key. The `data` contents will be passed as-is.
+
+These components pass all props through unchanged.
+
+## Framework support
+
+Currently supports **React / Preact** components (`.tsx`, `.ts`, `.jsx`, `.js`).
+
+The architecture uses a pluggable adapter pattern — Vue and Svelte adapters can be added without changing the core.
+
+## Debug logging
+
+In Astro's verbose mode, airlock logs per-component status:
+
+```
+[@astroscope/airlock] transformed 3 of 4 hydrated component usage(s)
+```
+
+Components that aren't transformed (ALLOW_ALL types, no user props) are logged at debug level with the reason.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { AstroIntegration } from 'astro';
+
+interface AirlockOptions {
+}
+
+/**
+ * astro integration that strips excess props from hydrated islands,
+ * preventing accidental server data leakage to the client.
+ */
+declare function airlock(_options?: AirlockOptions): AstroIntegration;
+
+export { type AirlockOptions, airlock as default };

package/dist/index.js

@@ -0,0 +1,607 @@
+// src/vite-plugin.ts
+import fs from "fs/promises";
+
+// src/adapters/react.ts
+import path from "path";
+import ts2 from "typescript";
+
+// src/extractor.ts
+import ts from "typescript";
+function generateZodSchema(checker, propsType) {
+  const ctx = { visiting: /* @__PURE__ */ new Set(), types: /* @__PURE__ */ new Map(), counter: 0 };
+  const root = toZod(checker, propsType, ctx);
+  if (root === null) return null;
+  return {
+    root,
+    types: [...ctx.types.values()].map((t) => `const ${t.name}: z.ZodType<any> = z.lazy(() => ${t.code});`)
+  };
+}
+function toZod(checker, type, ctx) {
+  if (ctx.visiting.has(type)) return getOrCreateLazyRef(checker, type, ctx);
+  const unwrapped = unwrapOptional(type);
+  if (isLeaf(unwrapped)) return null;
+  if (unwrapped.isUnion() && unwrapped.types.every((t) => isLeaf(t))) return null;
+  if (checker.isArrayType(type) || checker.isArrayType(unwrapped)) {
+    return arrayToZod(checker, checker.isArrayType(type) ? type : unwrapped, ctx);
+  }
+  if (hasIndexSignature(checker, unwrapped)) return null;
+  if (unwrapped.isUnion()) {
+    const discriminant = findDiscriminant(checker, unwrapped);
+    if (discriminant) return discriminatedUnionToZod(checker, unwrapped, discriminant, ctx);
+  }
+  const properties = collectProperties(checker, unwrapped);
+  if (!properties) return null;
+  return propsToZodObject(checker, properties, type, ctx);
+}
+function propsToZodObject(checker, properties, type, ctx) {
+  if (properties.size === 0) return "z.object({})";
+  ctx.visiting.add(type);
+  const fields = [];
+  for (const [name, prop] of properties) {
+    const propType = checker.getTypeOfSymbol(prop);
+    if (propType.getCallSignatures().length > 0 && !propType.getProperties().length) {
+      fields.push(`${safeKey(name)}: z.any()`);
+      continue;
+    }
+    fields.push(`${safeKey(name)}: ${toZod(checker, propType, ctx) ?? "z.any()"}`);
+  }
+  ctx.visiting.delete(type);
+  return `z.object({${fields.join(", ")}})`;
+}
+function collectProperties(checker, type) {
+  const result = /* @__PURE__ */ new Map();
+  if (type.isUnion() || type.isIntersection()) {
+    for (const member of type.types) {
+      if (hasIndexSignature(checker, member)) return null;
+      for (const prop of member.getProperties()) {
+        result.set(prop.name, prop);
+      }
+    }
+  } else {
+    for (const prop of type.getProperties()) {
+      result.set(prop.name, prop);
+    }
+  }
+  return result;
+}
+function arrayToZod(checker, arrayType, ctx) {
+  const typeArgs = arrayType.typeArguments;
+  if (!typeArgs?.length) return "z.any()";
+  const elementZod = toZod(checker, typeArgs[0], ctx) ?? "z.any()";
+  return `z.array(${elementZod})`;
+}
+function discriminatedUnionToZod(checker, union, discriminant, ctx) {
+  const variants = [];
+  for (const member of union.types) {
+    if (!isObjectLike(member)) continue;
+    const fields = [];
+    for (const prop of member.getProperties()) {
+      const propType = checker.getTypeOfSymbol(prop);
+      if (prop.name === discriminant && isLiteralType(propType)) {
+        fields.push(`${safeKey(prop.name)}: z.literal(${getLiteralValue(propType)})`);
+      } else {
+        fields.push(`${safeKey(prop.name)}: ${toZod(checker, propType, ctx) ?? "z.any()"}`);
+      }
+    }
+    variants.push(`z.object({${fields.join(", ")}})`);
+  }
+  return `z.discriminatedUnion(${JSON.stringify(discriminant)}, [${variants.join(", ")}])`;
+}
+function getOrCreateLazyRef(checker, type, ctx) {
+  const existing = ctx.types.get(type);
+  if (existing) return existing.name;
+  const name = `__zr${ctx.counter++}`;
+  ctx.types.set(type, { name, code: "" });
+  ctx.visiting.delete(type);
+  const code = toZod(checker, type, ctx) ?? "z.any()";
+  ctx.types.set(type, { name, code });
+  return name;
+}
+function findDiscriminant(checker, union) {
+  if (union.types.length < 2) return null;
+  const firstMember = union.types[0];
+  for (const prop of firstMember.getProperties()) {
+    if (!isLiteralType(checker.getTypeOfSymbol(prop))) continue;
+    const allHaveLiteral = union.types.every((member) => {
+      const memberProp = member.getProperty(prop.name);
+      return memberProp ? isLiteralType(checker.getTypeOfSymbol(memberProp)) : false;
+    });
+    if (allHaveLiteral) return prop.name;
+  }
+  return null;
+}
+function isLeaf(type) {
+  return isPrimitive(type) || !!(type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown));
+}
+function isPrimitive(type) {
+  const flags = (
+    // serializable primitives
+    ts.TypeFlags.String | ts.TypeFlags.Number | ts.TypeFlags.Boolean | ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.StringLiteral | ts.TypeFlags.NumberLiteral | ts.TypeFlags.BooleanLiteral | ts.TypeFlags.EnumLiteral | // not serializable but allowed — astro will error on these before airlock matters
+    ts.TypeFlags.Void | ts.TypeFlags.BigInt | ts.TypeFlags.BigIntLiteral | ts.TypeFlags.ESSymbol | ts.TypeFlags.Never
+  );
+  return (type.flags & flags) !== 0;
+}
+function isObjectLike(type) {
+  return !isLeaf(type);
+}
+function isLiteralType(type) {
+  return !!(type.flags & (ts.TypeFlags.StringLiteral | ts.TypeFlags.NumberLiteral | ts.TypeFlags.BooleanLiteral));
+}
+function getLiteralValue(type) {
+  if (type.isStringLiteral()) return JSON.stringify(type.value);
+  if (type.isNumberLiteral()) return String(type.value);
+  if (type.flags & ts.TypeFlags.BooleanLiteral) {
+    return type.intrinsicName === "true" ? "true" : "false";
+  }
+  return JSON.stringify(String(type));
+}
+function hasIndexSignature(checker, type) {
+  try {
+    return checker.getIndexTypeOfType(type, ts.IndexKind.String) !== void 0;
+  } catch {
+    return false;
+  }
+}
+function unwrapOptional(type) {
+  if (!type.isUnion()) return type;
+  const filtered = type.types.filter((t) => !(t.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null)));
+  if (filtered.length === 1) return filtered[0];
+  return type;
+}
+function safeKey(name) {
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+// src/adapters/react.ts
+var ReactAdapter = class {
+  name = "react";
+  extensions = [".tsx", ".ts", ".jsx", ".js"];
+  program = null;
+  projectRoot;
+  logger;
+  constructor(projectRoot, logger) {
+    this.projectRoot = projectRoot;
+    this.logger = logger;
+  }
+  canHandle(filePath) {
+    return this.extensions.some((ext) => filePath.endsWith(ext));
+  }
+  extractSchema(filePath, exportName) {
+    const prog = this.getProgram();
+    const checker = prog.getTypeChecker();
+    const sourceFile = prog.getSourceFile(filePath);
+    if (!sourceFile) {
+      this.logger.warn(`resolved ${filePath} but failed to load source file`);
+      return void 0;
+    }
+    const propsType = this.resolvePropsType(checker, sourceFile, exportName);
+    if (!propsType) return null;
+    return generateZodSchema(checker, propsType);
+  }
+  invalidate(_filePath) {
+    this.program = null;
+  }
+  resolveModulePath(importSpecifier, fromFile) {
+    const prog = this.getProgram();
+    const resolved = ts2.resolveModuleName(importSpecifier, fromFile, prog.getCompilerOptions(), ts2.sys);
+    if (!resolved.resolvedModule) {
+      this.logger.warn(`could not resolve '${importSpecifier}' from ${fromFile}`);
+      return void 0;
+    }
+    return resolved.resolvedModule.resolvedFileName;
+  }
+  /**
+   * resolve the props type for a React component export.
+   * handles function declarations, arrow functions, React.FC<Props>, etc.
+   */
+  resolvePropsType(checker, sourceFile, exportName) {
+    const symbol = this.getExportSymbol(checker, sourceFile, exportName);
+    if (!symbol) return void 0;
+    const symbolType = checker.getTypeOfSymbol(symbol);
+    const callSignatures = symbolType.getCallSignatures();
+    if (callSignatures.length === 0) return void 0;
+    const params = callSignatures[0].getParameters();
+    if (params.length === 0) return void 0;
+    return checker.getTypeOfSymbol(params[0]);
+  }
+  getExportSymbol(checker, sourceFile, exportName) {
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    if (!moduleSymbol) return void 0;
+    const exports = checker.getExportsOfModule(moduleSymbol);
+    const target = exportName === "default" ? "default" : exportName;
+    const exportSymbol = exports.find((s) => s.escapedName === target);
+    if (!exportSymbol) return void 0;
+    return this.resolveAlias(checker, exportSymbol);
+  }
+  resolveAlias(checker, symbol) {
+    if (symbol.flags & ts2.SymbolFlags.Alias) {
+      return this.resolveAlias(checker, checker.getAliasedSymbol(symbol));
+    }
+    return symbol;
+  }
+  getProgram() {
+    if (this.program) return this.program;
+    const tsconfigPath = path.join(this.projectRoot, "tsconfig.json");
+    const configFile = ts2.readConfigFile(tsconfigPath, ts2.sys.readFile);
+    const parsedConfig = ts2.parseJsonConfigFileContent(configFile.config, ts2.sys, this.projectRoot);
+    this.program = ts2.createProgram(parsedConfig.fileNames, parsedConfig.options);
+    return this.program;
+  }
+};
+
+// src/astro-analyze.ts
+import { parse } from "@astrojs/compiler";
+import ts3 from "typescript";
+async function analyzeAstroSource(raw) {
+  const { ast } = await parse(raw);
+  const frontmatterNode = ast.children.find((n) => n.type === "frontmatter");
+  const frontmatter = frontmatterNode?.value ?? "";
+  const imports = resolveImports(frontmatter);
+  const hydratedComponents = findHydratedComponents(ast.children, imports);
+  return { imports, hydratedComponents };
+}
+function resolveImports(frontmatter) {
+  const imports = /* @__PURE__ */ new Map();
+  if (!frontmatter) return imports;
+  const sourceFile = ts3.createSourceFile(
+    "__airlock__.ts",
+    frontmatter,
+    ts3.ScriptTarget.Latest,
+    false,
+    ts3.ScriptKind.TS
+  );
+  for (const stmt of sourceFile.statements) {
+    if (!ts3.isImportDeclaration(stmt)) continue;
+    if (!stmt.moduleSpecifier || !ts3.isStringLiteral(stmt.moduleSpecifier)) continue;
+    const specifier = stmt.moduleSpecifier.text;
+    const clause = stmt.importClause;
+    if (!clause) continue;
+    if (clause.name) {
+      imports.set(clause.name.text, { specifier, exportName: "default" });
+    }
+    if (clause.namedBindings && ts3.isNamedImports(clause.namedBindings)) {
+      for (const element of clause.namedBindings.elements) {
+        const localName = element.name.text;
+        const exportName = element.propertyName?.text ?? element.name.text;
+        imports.set(localName, { specifier, exportName });
+      }
+    }
+    if (clause.namedBindings && ts3.isNamespaceImport(clause.namedBindings)) {
+      imports.set(clause.namedBindings.name.text, { specifier, exportName: "*" });
+    }
+  }
+  return imports;
+}
+function findHydratedComponents(nodes, imports) {
+  const components = [];
+  function process(nodes2, visitor) {
+    for (const node of nodes2) {
+      visitor(node);
+      if ("children" in node && Array.isArray(node.children)) {
+        process(node.children, visitor);
+      }
+    }
+  }
+  process(nodes, (node) => {
+    if (node.type !== "component") return;
+    const comp = node;
+    if (!comp.attributes.some((a) => a.type === "attribute" && a.name.startsWith("client:"))) return;
+    components.push({
+      name: comp.name,
+      importInfo: imports.get(comp.name)
+    });
+  });
+  return components;
+}
+
+// src/dep-tracker.ts
+var DepTracker = class {
+  astroToDeps = /* @__PURE__ */ new Map();
+  depToAstros = /* @__PURE__ */ new Map();
+  /**
+   * record that an .astro file depends on a resolved component path.
+   */
+  track(astroFile, resolvedComponentPath) {
+    let deps = this.astroToDeps.get(astroFile);
+    if (!deps) {
+      deps = /* @__PURE__ */ new Set();
+      this.astroToDeps.set(astroFile, deps);
+    }
+    deps.add(resolvedComponentPath);
+    let astros = this.depToAstros.get(resolvedComponentPath);
+    if (!astros) {
+      astros = /* @__PURE__ */ new Set();
+      this.depToAstros.set(resolvedComponentPath, astros);
+    }
+    astros.add(astroFile);
+  }
+  /**
+   * clear all dependencies for an .astro file (before re-tracking).
+   */
+  clear(astroFile) {
+    const deps = this.astroToDeps.get(astroFile);
+    if (!deps) return;
+    for (const dep of deps) {
+      this.depToAstros.get(dep)?.delete(astroFile);
+    }
+    this.astroToDeps.delete(astroFile);
+  }
+  /**
+   * get all .astro files that depend on a component path.
+   */
+  getDependents(resolvedComponentPath) {
+    return this.depToAstros.get(resolvedComponentPath);
+  }
+};
+
+// src/schema-registry.ts
+var VIRTUAL_MODULE_ID = "virtual:@astroscope/airlock/schemas";
+var RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
+var SchemaRegistry = class {
+  schemas = /* @__PURE__ */ new Map();
+  adapters;
+  idCounter = 0;
+  constructor(adapters) {
+    this.adapters = adapters;
+  }
+  /**
+   * resolve an import specifier to a schema.
+   * registers the schema in the registry for virtual module emission.
+   */
+  resolve(importSpecifier, exportName, fromFile) {
+    for (const adapter of this.adapters) {
+      const filePath = adapter.resolveModulePath(importSpecifier, fromFile);
+      if (!filePath) continue;
+      if (!adapter.canHandle(filePath)) continue;
+      const cacheKey = `${filePath}#${exportName}`;
+      if (this.schemas.has(cacheKey)) return this.schemas.get(cacheKey);
+      const schema = adapter.extractSchema(filePath, exportName);
+      if (schema === void 0) continue;
+      const schemaId = `__s${this.idCounter++}`;
+      const result = { schema, resolvedPath: filePath, schemaId };
+      this.schemas.set(cacheKey, result);
+      return result;
+    }
+    return void 0;
+  }
+  /**
+   * generate the virtual module source code.
+   * each schema is exported as a named constant, created once.
+   */
+  generateVirtualModule() {
+    const lines = ["import { z } from 'astro/zod';"];
+    for (const entry of this.schemas.values()) {
+      if (entry.schema === null) continue;
+      const body = [...entry.schema.types, `return ${entry.schema.root};`].join("\n  ");
+      lines.push(`export const ${entry.schemaId} = (() => {
+  ${body}
+})();`);
+    }
+    lines.push(
+      "export function __airlock_strip(schema, props) {",
+      "  const clean = schema.parse(props);",
+      '  for (const k of Object.keys(props)) if (k.startsWith("client:")) clean[k] = props[k];',
+      "  return clean;",
+      "}"
+    );
+    return lines.join("\n");
+  }
+  /**
+   * invalidate cached schemas for a changed file.
+   */
+  invalidate(filePath) {
+    for (const adapter of this.adapters) {
+      if (adapter.canHandle(filePath)) {
+        adapter.invalidate(filePath);
+      }
+    }
+    for (const [key, value] of this.schemas) {
+      if (value.resolvedPath === filePath) {
+        this.schemas.delete(key);
+      }
+    }
+  }
+  /**
+   * check whether any adapter handles this file extension.
+   */
+  canHandle(filePath) {
+    return this.adapters.some((a) => a.canHandle(filePath));
+  }
+};
+
+// src/utils.ts
+import path2 from "path";
+function stripExt(filePath) {
+  const { dir, name } = path2.parse(filePath);
+  return path2.join(dir, name);
+}
+
+// src/transform.ts
+async function transformCompiledOutput(code, schemas) {
+  const babel = await import("@babel/core");
+  const schemaMap = /* @__PURE__ */ new Map();
+  for (const m of schemas) {
+    schemaMap.set(stripExt(m.componentPath), m.schemaId);
+  }
+  const matched = /* @__PURE__ */ new Set();
+  const usedSchemaIds = /* @__PURE__ */ new Set();
+  let renderComponentFound = false;
+  const plugin = ({ types: t }) => ({
+    visitor: {
+      ImportDeclaration(path3) {
+        if (!path3.node.source.value.includes("compiler-runtime")) return;
+        for (const specifier of path3.node.specifiers) {
+          if (specifier.type !== "ImportSpecifier") continue;
+          const imported = specifier.imported;
+          const importedName = "name" in imported ? imported.name : imported.value;
+          if (importedName !== "renderComponent") continue;
+          renderComponentFound = true;
+          const localName = specifier.local.name;
+          const binding = path3.scope.getBinding(localName);
+          if (!binding) break;
+          for (const refPath of binding.referencePaths) {
+            const callPath = refPath.parentPath;
+            if (!callPath?.isCallExpression()) continue;
+            const propsArg = callPath.node.arguments[3];
+            if (!propsArg || !t.isObjectExpression(propsArg)) continue;
+            const componentPath = getStringProp(t, propsArg);
+            if (!componentPath) continue;
+            const schemaId = schemaMap.get(componentPath);
+            if (!schemaId) continue;
+            matched.add(componentPath);
+            usedSchemaIds.add(schemaId);
+            callPath.node.arguments[3] = t.callExpression(t.identifier("__airlock_strip"), [
+              t.identifier(schemaId),
+              propsArg
+            ]);
+          }
+          break;
+        }
+      }
+    }
+  });
+  const result = babel.transformSync(code, {
+    plugins: [plugin],
+    sourceType: "module",
+    sourceMaps: true,
+    configFile: false,
+    babelrc: false
+  });
+  if (!renderComponentFound) {
+    throw new Error(
+      "[@astroscope/airlock] could not find renderComponent import in compiled output. this may indicate a breaking change in Astro's compilation format. airlock refuses to continue to prevent potential data leaks."
+    );
+  }
+  for (const m of schemas) {
+    const pathWithoutExt = stripExt(m.componentPath);
+    if (!matched.has(pathWithoutExt)) {
+      throw new Error(
+        `[@astroscope/airlock] component "${pathWithoutExt}" was detected in .astro source but not found in compiled output. airlock refuses to continue to prevent potential data leaks.`
+      );
+    }
+  }
+  if (!result?.code) {
+    throw new Error("[@astroscope/airlock] babel transform returned no output.");
+  }
+  const imports = [...usedSchemaIds, "__airlock_strip"];
+  const importLine = `import { ${imports.join(", ")} } from '${VIRTUAL_MODULE_ID}';`;
+  return {
+    code: `${importLine}
+${result.code}`,
+    map: result.map
+  };
+}
+function getStringProp(t, obj) {
+  for (const prop of obj.properties) {
+    if (!t.isObjectProperty(prop)) continue;
+    let propName = null;
+    if (t.isIdentifier(prop.key)) propName = prop.key.name;
+    else if (t.isStringLiteral(prop.key)) propName = prop.key.value;
+    if (propName !== "client:component-path") continue;
+    if (t.isStringLiteral(prop.value)) return prop.value.value;
+  }
+  return null;
+}
+
+// src/vite-plugin.ts
+function airlockVitePlugin(options) {
+  const { logger } = options;
+  const deps = new DepTracker();
+  let totalSeen = 0;
+  let totalTransformed = 0;
+  let registry;
+  let server;
+  return {
+    name: "@astroscope/airlock",
+    // note: no applyToEnvironment — handleHotUpdate must fire for all environments
+    // the transform hook checks for .astro files, so client env is skipped naturally
+    configResolved(config) {
+      registry = new SchemaRegistry([new ReactAdapter(config.root, logger)]);
+    },
+    configureServer(devServer) {
+      server = devServer;
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID) return RESOLVED_VIRTUAL_MODULE_ID;
+    },
+    load(id) {
+      if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+        return registry.generateVirtualModule();
+      }
+    },
+    async transform(code, id) {
+      if (!id.endsWith(".astro")) return;
+      const raw = await fs.readFile(id, "utf-8");
+      if (!raw.includes("client:")) return;
+      const analyzed = await analyzeAstroSource(raw);
+      if (!analyzed.hydratedComponents.length) return;
+      deps.clear(id);
+      const componentsToWrap = [];
+      for (const comp of analyzed.hydratedComponents) {
+        totalSeen++;
+        if (!comp.importInfo) {
+          logger.warn(`<${comp.name}> \u2014 no matching import`);
+          continue;
+        }
+        const resolved = registry.resolve(comp.importInfo.specifier, comp.importInfo.exportName, id);
+        if (!resolved) {
+          logger.warn(`<${comp.name}> (${comp.importInfo.specifier}) \u2014 not resolved`);
+          continue;
+        }
+        if (comp.importInfo.specifier) {
+          deps.track(id, resolved.resolvedPath);
+        }
+        if (resolved.schema === null) {
+          logger.debug(`<${comp.name}> (${comp.importInfo.specifier}) \u2014 ALLOW_ALL`);
+          continue;
+        }
+        componentsToWrap.push({ componentPath: resolved.resolvedPath, schemaId: resolved.schemaId });
+      }
+      if (componentsToWrap.length === 0) return;
+      if (server) {
+        const virtualMod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULE_ID);
+        if (virtualMod) {
+          server.moduleGraph.invalidateModule(virtualMod);
+        }
+      }
+      const result = await transformCompiledOutput(code, componentsToWrap);
+      totalTransformed += componentsToWrap.length;
+      return result;
+    },
+    closeBundle() {
+      if (!totalSeen && !totalTransformed) return;
+      logger.info(`transformed ${totalTransformed} of ${totalSeen} hydrated component usage(s)`);
+    },
+    handleHotUpdate({ file }) {
+      if (!server || !registry.canHandle(file)) return;
+      registry.invalidate(file);
+      const dependents = deps.getDependents(file);
+      if (!dependents) return;
+      for (const astroFile of dependents) {
+        const mod = server.moduleGraph.getModuleById(astroFile);
+        if (mod) {
+          server.reloadModule(mod);
+        }
+      }
+    }
+  };
+}
+
+// src/integration.ts
+function airlock(_options = {}) {
+  return {
+    name: "@astroscope/airlock",
+    hooks: {
+      "astro:config:setup": ({ updateConfig, logger }) => {
+        updateConfig({
+          vite: {
+            plugins: [airlockVitePlugin({ logger })]
+          }
+        });
+      }
+    }
+  };
+}
+export {
+  airlock as default
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@astroscope/airlock",
+  "version": "0.1.0",
+  "description": "Strip excess props from hydrated Astro islands to prevent server data leakage",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smnbbrv/astroscope.git",
+    "directory": "packages/airlock"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "security",
+    "performance",
+    "data-leak-prevention",
+    "props",
+    "islands",
+    "serialization"
+  ],
+  "author": "smnbbrv",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/smnbbrv/astroscope/issues"
+  },
+  "homepage": "https://github.com/smnbbrv/astroscope/tree/main/packages/airlock#readme",
+  "dependencies": {
+    "@astrojs/compiler": "^3.0.0",
+    "@babel/core": "^7.29.0"
+  },
+  "devDependencies": {
+    "@babel/types": "^7.29.0",
+    "@types/babel__core": "^7.20.5",
+    "astro": "^6.0.7",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  },
+  "peerDependencies": {
+    "astro": "^6.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^7.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --external @astrojs/compiler --external @babel/core",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "preview": "astro preview"
+  }
+}