frontier-os-app-builder 1.1.0 → 1.2.0

package/references/deployment.md

@@ -18,13 +18,6 @@ All Frontier OS apps deploy to Vercel. The `vercel.json` file is identical acros
   "headers": [
     {
       "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "https://os.frontiertower.io"
-        }
-      ],
       "headers": [
         {
           "key": "Access-Control-Allow-Origin",
@@ -37,54 +30,22 @@ All Frontier OS apps deploy to Vercel. The `vercel.json` file is identical acros
         {
           "key": "Access-Control-Allow-Headers",
           "value": "Content-Type"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "https://sandbox.os.frontiertower.io"
-        }
-      ],
-      "headers": [
-        {
-          "key": "Access-Control-Allow-Origin",
-          "value": "https://sandbox.os.frontiertower.io"
         },
         {
-          "key": "Access-Control-Allow-Methods",
-          "value": "GET, OPTIONS"
+          "key": "Content-Security-Policy",
+          "value": "frame-ancestors https://os.frontiertower.io https://sandbox.os.frontiertower.io http://localhost:5173;"
         },
         {
-          "key": "Access-Control-Allow-Headers",
-          "value": "Content-Type"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "http://localhost:5173"
-        }
-      ],
-      "headers": [
-        {
-          "key": "Access-Control-Allow-Origin",
-          "value": "http://localhost:5173"
+          "key": "X-Content-Type-Options",
+          "value": "nosniff"
         },
         {
-          "key": "Access-Control-Allow-Methods",
-          "value": "GET, OPTIONS"
+          "key": "Referrer-Policy",
+          "value": "strict-origin-when-cross-origin"
         },
         {
-          "key": "Access-Control-Allow-Headers",
-          "value": "Content-Type"
+          "key": "Permissions-Policy",
+          "value": "camera=(), microphone=(), geolocation=()"
         }
       ]
     }
@@ -92,15 +53,15 @@ All Frontier OS apps deploy to Vercel. The `vercel.json` file is identical acros
 }
 ```
 
-### Why 3 Separate Blocks
+### One Header Block + CSP `frame-ancestors`
 
-Vercel does not support multiple values in a single `Access-Control-Allow-Origin` header. Each allowed origin requires its own conditional header block using the `has` matcher. The `has` condition checks the incoming `Origin` request header and only attaches the CORS response headers when the origin matches.
+A single unconditional header block applies CORS for the production origin plus the security headers to every response. Embedding by all three Frontier origins is granted by the `Content-Security-Policy: frame-ancestors` directive (which lists all three) — `frame-ancestors` is what actually governs iframe embedding, not per-origin CORS reflection. This replaces the older pattern of one `has`-matched CORS block per origin.
 
 ---
 
 ## Allowed Origins
 
-The Frontier Wallet PWA runs at these 3 origins. Apps must allow CORS from all of them:
+The Frontier Wallet PWA runs at these 3 origins. Apps must allow all of them to embed the app via the CSP `frame-ancestors` directive:
 
 | Origin                                    | Environment  | Description                                                    |
 | ----------------------------------------- | ------------ | -------------------------------------------------------------- |
@@ -108,7 +69,7 @@ The Frontier Wallet PWA runs at these 3 origins. Apps must allow CORS from all o
 | `https://sandbox.os.frontiertower.io`     | Sandbox      | Sandbox environment                                            |
 | `https://os.frontiertower.io`             | Production   | Production ready                                               |
 
-These origins are also hardcoded in the SDK at `@frontiertower/frontier-sdk/ui-utils/detection.ts` as `ALLOWED_ORIGINS`.
+These origins are also hardcoded in the SDK at `@frontiertower/frontier-sdk/ui-utils/detection.ts` as `ALLOWED_ORIGINS` (exactly these 3). Note: `isInFrontierApp()` no longer consults this list -- it returns `window.self !== window.top` -- so `ALLOWED_ORIGINS` is informational for CORS/CSP only.
 
 The `isInFrontierApp()` function checks `window.self !== window.top` to detect if the app is running inside the Frontier Wallet iframe. The `getParentOrigin()` function resolves the parent frame's origin via `document.referrer` or `window.parent.location.origin`.
 
@@ -118,16 +79,16 @@ The `isInFrontierApp()` function checks `window.self !== window.top` to detect i
 
 ## Security Headers
 
-In addition to CORS, all deployment targets should include:
+The `vercel.json` above already ships these alongside CORS — every app should keep them:
 
-| Header                       | Recommended Value                                  | Purpose                                     |
+| Header                       | Value (shipped in vercel.json)                     | Purpose                                     |
 | ---------------------------- | -------------------------------------------------- | ------------------------------------------- |
-| `Content-Security-Policy`    | Include `frame-ancestors` for all 3 Frontier origins | Prevents embedding by unauthorized sites   |
+| `Content-Security-Policy`    | `frame-ancestors https://os.frontiertower.io https://sandbox.os.frontiertower.io http://localhost:5173;` (the 3 live origins) | Restricts who may embed the app             |
 | `X-Content-Type-Options`     | `nosniff`                                          | Prevents MIME-type sniffing                 |
 | `Referrer-Policy`            | `strict-origin-when-cross-origin`                  | Controls referrer information leakage       |
-| `Permissions-Policy`         | Disable unnecessary browser APIs                   | Reduces attack surface                      |
+| `Permissions-Policy`         | `camera=(), microphone=(), geolocation=()`         | Disables unused browser APIs                |
 
-The `frame-ancestors` CSP directive is critical because apps load inside the PWA's iframe. Without it, the browser may block the embed.
+The `frame-ancestors` CSP directive is critical because apps load inside the PWA's iframe. Without it, the browser may block the embed. The CSP is intentionally limited to `frame-ancestors` so it never blocks app resources (e.g. the Google Fonts stylesheet the template loads); apps that self-host all assets may tighten it further.
 
 ---
 
@@ -142,7 +103,7 @@ The recommended way is to use the OS Developer app in the Frontier AppStore. The
 1. **Get developer access** -- contact support@frontiertower.io to be added as a developer manager.
 2. **Get your developer profile** -- install the OS Developer app from the AppStore, or call `GET /third-party/developers/`.
 3. **Rotate your API key** immediately after receiving it: `POST /third-party/developers/{developer_id}/rotate-key/`. Store the new key securely.
-4. **Create the app** -- via OS Developer or `POST /third-party/apps/` with metadata: `name`, `url`, `description`, optional DNS entries.
+4. **Create the app** -- via OS Developer (`sdk.getThirdParty().createApp(...)`) or `POST /third-party/apps/` with body `{ url, cnameEntry, txtEntry?, permissions: string[], permissionDisclaimer }` (OS Developer additionally sends `developer: <id>`). App `name`, `description`, and `icon` are NOT sent -- they are auto-fetched from the app URL's HTML metadata (`<title>`, `<meta name="description">`, `<link rel="icon">`).
 
 ### App Status Lifecycle
 
@@ -167,24 +128,29 @@ When registering, declare the SDK permissions your app requires:
 ```typescript
 const APP_REGISTRY: AppMetadata[] = [
   {
-    id: 'my-app',
-    url: 'https://my-app.appstore.frontiertower.io',
-    origin: 'https://my-app.appstore.frontiertower.io',
-    version: '1.0.0',
+    id: 'ifnd-converter',
+    url: 'https://ifnd-converter.apps.frontiertower.io',
+    icon: '/svgs/ifnd_converter.svg',
     developer: {
       name: 'Developer Name',
-      verified: true,
-    },
-    permissions: {
-      wallet: true,
-      storage: true,
-      notifications: false,
+      url: 'https://frontiertower.io',
+      description: 'Made with love by the Frontier Tower Action Team',
     },
+    permissions: [
+      'wallet:getBalance',
+      'wallet:getAddress',
+      'wallet:executeBatchCall',
+      'wallet:executeCall',
+      'chain:getCurrentChainConfig',
+    ],
+    permissionDisclaimer:
+      'This app accesses your wallet address and balance and executes the conversion calls.',
+    // optional: excludedAppStages?, requiresCitizenship?, requiresAdmin?
   } as AppMetadata,
 ];
 ```
 
-Permissions must match the SDK methods actually called in source code. The fos-verifier agent enforces this (see [verification-rules.md](verification-rules.md)).
+Permissions are a flat array of `module:method` strings -- each entry must match an SDK method actually called in source code. `name`, `description`, and `icon` are optional in `AppMetadata` (auto-fetched from the app's HTML when omitted). There is no `origin`, `version`, or `developer.verified` field, and there is no `notifications` permission. The fos-verifier agent enforces the permission-to-source match (see [verification-rules.md](verification-rules.md)).
 
 ---
 
@@ -210,15 +176,15 @@ VITE_API_URL=https://api.example.com
 
 ## DNS Configuration
 
-Apps are hosted on the `appstore.frontiertower.io` subdomain.
+Apps are hosted on the `apps.frontiertower.io` subdomain.
 
 ### Domain Pattern
 
 ```
-<app-name>.appstore.frontiertower.io
+<app-name>.apps.frontiertower.io
 ```
 
-Example: `kickstarter.appstore.frontiertower.io`
+Example: `kickstarter.apps.frontiertower.io`
 
 ### DNS Entries
 
@@ -226,12 +192,12 @@ Two DNS records are needed:
 
 1. **CNAME** -- points the subdomain to the Vercel deployment:
    ```
-   <app-name>.appstore.frontiertower.io  CNAME  cname.vercel-dns.com
+   <app-name>.apps.frontiertower.io  CNAME  cname.vercel-dns.com
    ```
 
 2. **TXT** -- Vercel domain verification:
    ```
-   _vercel.<app-name>.appstore.frontiertower.io  TXT  vc-domain-verify=<token>
+   _vercel.<app-name>.apps.frontiertower.io  TXT  vc-domain-verify=<token>
    ```
 
 Configure the custom domain in the Vercel dashboard after DNS propagation. Vercel automatically provisions an SSL certificate.
@@ -331,7 +297,7 @@ Call `POST /third-party/webhooks/{webhook_id}/rotate-key/`. Deliveries immediate
 After deploying, verify CORS is working:
 
 ```bash
-curl -I https://<app-name>.appstore.frontiertower.io \
+curl -I https://<app-name>.apps.frontiertower.io \
   -H "Origin: https://os.frontiertower.io"
 
 # Should include:

package/references/module-index.md

@@ -0,0 +1,32 @@
+# SDK Module Index
+
+Maps app descriptions to Frontier SDK modules. The CLI (`fos-tools.cjs infer-modules`) does keyword matching programmatically — this file documents the algorithm and serves as an index to per-module reference files.
+
+## Inference Algorithm
+
+This mirrors `cmdInferModules` in `fos-tools.cjs` exactly:
+
+1. Lowercase the entire description (`description.toLowerCase()`) — no tokenization or word splitting.
+2. For each SDK module, substring-match its trigger keywords against the lowercased description with `String.includes()` (keywords are listed in each module's reference file under `references/sdk/`). Because matching is by substring, multi-word phrases like `send money`, `access control`, and `api key` work, and a keyword can match inside a larger word (e.g. `fund` matches within `refund`).
+3. Always include Storage and Chain (the base modules — every app needs these).
+4. Include User if User's own keywords match, or if any of Wallet, Events, Communities, Partnerships, or Offices matched. User is NOT added by ThirdParty, Navigation, Storage, or Chain alone.
+5. Present the inferred modules for user confirmation.
+
+## Module Quick Reference
+
+| Module | Reference File | Primary Use Case |
+|--------|---------------|-----------------|
+| Wallet | `references/sdk/wallet.md` | Payments, transfers, FND/iFND, fiat on/off-ramp |
+| Storage | `references/sdk/storage.md` | Key-value persistence, preferences |
+| Chain | `references/sdk/chain.md` | Network config, contract addresses |
+| User | `references/sdk/user.md` | Profiles, access controls, membership |
+| Communities | `references/sdk/communities.md` | Groups, internships, member management |
+| Partnerships | `references/sdk/partnerships.md` | Sponsors, passes, brand partnerships |
+| Events | `references/sdk/events.md` | Calendar, rooms, bookings, RSVPs |
+| Offices | `references/sdk/offices.md` | Physical access passes, building entry |
+| ThirdParty | `references/sdk/thirdparty.md` | Developer tools, webhooks, API keys |
+| Navigation | `references/sdk/navigation.md` | Deep links, cross-app navigation |
+
+## After Inference
+
+Once modules are confirmed, read only the relevant `references/sdk/<module>.md` files for detailed method signatures, types, and permissions. Always include `references/sdk/init.md` and `references/sdk/types.md` as shared context. For any app that reads, displays, transfers, or swaps FND amounts, also read `references/sdk/token-amount.md` — FND amounts are `bigint` base units bridged to/from display strings via `formatAmount()`/`parseAmount()`.

package/references/sdk/chain.md

@@ -0,0 +1,92 @@
+# Chain Module
+
+**Trigger keywords:** network, chain, blockchain, contract, smart contract, on-chain, token address, stablecoin
+
+Access via `sdk.getChain()`. Query and switch blockchain networks.
+
+---
+
+## Methods
+
+```typescript
+getCurrentNetwork(): Promise<string>
+```
+Returns the current network identifier (e.g. `'base'`, `'base-sepolia'`). Permission: `chain:getCurrentNetwork`
+
+```typescript
+getAvailableNetworks(): Promise<string[]>
+```
+Returns all network identifiers the app can switch to. Permission: `chain:getAvailableNetworks`
+
+```typescript
+switchNetwork(network: string): Promise<void>
+```
+Switch active blockchain network. Affects all subsequent wallet operations. Permission: `chain:switchNetwork`
+
+```typescript
+getCurrentChainConfig(): Promise<ChainConfig>
+```
+Returns full chain configuration for the current network. Permission: `chain:getCurrentChainConfig`
+
+```typescript
+getContractAddresses(): Promise<{
+  fnd: string;
+  iFnd: string | null;
+  paymentRouter: string;
+  subscriptionManager: string;
+}>
+```
+Returns addresses for FND, iFND (may be null), PaymentRouter, and SubscriptionManager contracts on the current chain. Permission: `chain:getContractAddresses`
+
+---
+
+## Types
+
+```typescript
+enum Underlying {
+  USD = "USD",
+}
+
+interface Token {
+  name: string;
+  symbol: string;
+  decimals: number;
+  address: string;
+}
+
+interface StableCoin extends Token {
+  underlying: Underlying;
+}
+
+interface ChainConfig {
+  id: number;
+  name: string;
+  network: string;
+  bridgeSwapRouterFactoryAddress: string;
+  uniswapV3FactoryAddress: string;
+  nativeCurrency: {
+    name: string;
+    symbol: string;
+    decimals: number;
+  };
+  blockExplorer: {
+    name: string;
+    url: string;
+  };
+  stableCoins: StableCoin[];
+  supportedTokens: Token[];
+  testnet: boolean;
+}
+```
+
+---
+
+## Permissions (5)
+
+| Permission | Description |
+|---|---|
+| `chain:getCurrentNetwork` | Get current network name |
+| `chain:getAvailableNetworks` | Get list of available networks |
+| `chain:switchNetwork` | Switch to a different network |
+| `chain:getCurrentChainConfig` | Get full chain configuration |
+| `chain:getContractAddresses` | Get FND, iFND, PaymentRouter, SubscriptionManager addresses |

package/references/sdk/communities.md

@@ -0,0 +1,159 @@
+# Communities Module
+
+**Trigger keywords:** community, group, team, club, internship, intern, cohort, reassign, transfer member, collective, society
+
+Access via `sdk.getCommunities()`. Manage communities, internship passes, and member reassignment requests.
+
+Community listing is public. Internship passes require authentication, an active subscription, and community manager status. Reassign requests require authentication; creating requires managing the member's current community, accepting requires managing the target community. Superusers can access everything.
+
+---
+
+## Methods
+
+```typescript
+listCommunities(payload?: ListCommunitiesParams): Promise<PaginatedResponse<Community>>
+```
+List all visible communities, paginated. Permission: `communities:listCommunities`
+
+```typescript
+getCommunity(payload: { idOrSlug: string | number }): Promise<Community>
+```
+Get a community by numeric ID or slug string. Permission: `communities:getCommunity`
+
+```typescript
+createInternshipPass(payload: CreateInternshipPassRequest): Promise<InternshipPass>
+```
+Create an internship pass. Auto-creates an inactive account if the user does not exist. Permission: `communities:createInternshipPass`
+
+```typescript
+listInternshipPasses(payload?: ListInternshipPassesParams): Promise<PaginatedResponse<InternshipPass>>
+```
+List internship passes for managed communities. Active only by default; set `includeRevoked: true` to include revoked. Permission: `communities:listInternshipPasses`
+
+```typescript
+getInternshipPass(payload: { id: number }): Promise<InternshipPass>
+```
+Get an internship pass by ID. Permission: `communities:getInternshipPass`
+
+```typescript
+revokeInternshipPass(payload: { id: number }): Promise<void>
+```
+Revoke an internship pass. Cannot revoke an already-revoked pass. Permission: `communities:revokeInternshipPass`
+
+```typescript
+createReassignRequest(payload: CreateReassignRequestPayload): Promise<ReassignRequest>
+```
+Request to move a member to a different community. Caller must manage the member's current community. Permission: `communities:createReassignRequest`
+
+```typescript
+listReassignRequests(payload?: ListReassignRequestsParams): Promise<PaginatedResponse<ReassignRequest>>
+```
+List pending reassign requests visible to the caller. Permission: `communities:listReassignRequests`
+
+```typescript
+getReassignRequest(payload: { id: number }): Promise<ReassignRequest>
+```
+Get a reassign request by ID. Permission: `communities:getReassignRequest`
+
+```typescript
+acceptReassignRequest(payload: { id: number }): Promise<ReassignRequest>
+```
+Accept a reassign request. Moves the member to the target community. Only target community managers (or superusers) can accept. Permission: `communities:acceptReassignRequest`
+
+```typescript
+rejectReassignRequest(payload: { id: number }): Promise<void>
+```
+Reject a reassign request. Only pending requests can be rejected. Permission: `communities:rejectReassignRequest`
+
+---
+
+## Types
+
+```typescript
+interface Community {
+  id: number;
+  name: string;
+  description: string;
+  slug: string;
+  iconName: string;
+  splashVideo: string | null;
+}
+
+interface ListCommunitiesParams {
+  limit?: number;
+  offset?: number;
+}
+
+type InternshipPassStatus = 'active' | 'revoked';
+
+interface InternshipPass {
+  id: number;
+  email: string;
+  firstName: string;
+  lastName: string;
+  community: number;
+  communityName: string;
+  status: InternshipPassStatus;
+  createdAt: string;
+  revokedAt: string | null;
+  updatedAt: string;
+}
+
+interface CreateInternshipPassRequest {
+  email: string;
+  firstName: string;
+  lastName: string;
+  community: number;
+}
+
+interface ListInternshipPassesParams {
+  limit?: number;
+  offset?: number;
+  includeRevoked?: boolean;
+}
+
+type ReassignRequestStatus = 'pending' | 'accepted' | 'rejected';
+
+interface ReassignRequest {
+  id: number;
+  requester: number;
+  requesterEmail: string;
+  member: number;
+  memberEmail: string;
+  targetCommunity: number;
+  targetCommunityName: string;
+  status: ReassignRequestStatus;
+  createdAt: string;
+  resolvedAt: string | null;
+  resolvedBy: number | null;
+  resolvedByEmail: string | null;
+}
+
+interface CreateReassignRequestPayload {
+  memberEmail: string;
+  targetCommunity: number;
+}
+
+interface ListReassignRequestsParams {
+  limit?: number;
+  offset?: number;
+}
+```
+
+---
+
+## Permissions (11)
+
+| Permission | Description |
+|---|---|
+| `communities:listCommunities` | List all visible communities (paginated) |
+| `communities:getCommunity` | Get a community by ID or slug |
+| `communities:createInternshipPass` | Create an internship pass for a managed community |
+| `communities:listInternshipPasses` | List internship passes for managed communities |
+| `communities:getInternshipPass` | Retrieve an internship pass by ID |
+| `communities:revokeInternshipPass` | Revoke an internship pass |
+| `communities:createReassignRequest` | Create a member reassignment request |
+| `communities:listReassignRequests` | List pending reassignment requests |
+| `communities:getReassignRequest` | Retrieve a reassignment request by ID |
+| `communities:acceptReassignRequest` | Accept a reassignment request (moves member) |
+| `communities:rejectReassignRequest` | Reject a reassignment request |