Enterprise foundation — org CRUD, billing modes, SSO, dashboard

.env.sample

@@ -92,3 +92,20 @@ NEXT_PUBLIC_LOGO_DEV_TOKEN=""
 # PAN encryption key for consultant tax info (AES-256-GCM)
 # Generate with: openssl rand -hex 32
 PAN_ENCRYPTION_KEY=""
+# Organization payout account encryption (AES-256-GCM)
+# Generate with: openssl rand -hex 32
+ORG_PAYOUT_ENCRYPTION_KEY=""
+
+# GST place-of-supply: the supplier's (i.e. Familiarise's) state code.
+# Used by lib/compliance/gst.ts to decide CGST+SGST (intra-state) vs IGST
+# (inter-state). Defaults to "KA" (Karnataka). Change when the business
+# address or the GSTIN's registered state changes; CA sign-off recommended.
+SUPPLIER_STATE_CODE="KA"
+
+# Enterprise — consolidated-invoice rollup cron flag.
+# When "true", the monthly consolidated-invoice cron rolls up children's
+# unpaid OrganizationInvoice rows into a single parent-org invoice on the
+# 1st of the month. Defaults to "false" because org hierarchy is still
+# schema-only for most tenants; enable once a parent tenant requires
+# consolidated billing. See app/api/cleanup/consolidated-invoice-rollup/.
+ENABLE_CONSOLIDATED_INVOICE="false"

.github/workflows/ci.yaml

@@ -103,6 +103,12 @@ jobs:
       - name: Generate Prisma Client
         run: npx prisma generate
 
+      - name: Verify SSO invariants
+        # Cheap static guard against regressions in the SSO audit fixes
+        # (PR #655 / issue #672). See scripts/verify-sso-invariants.sh
+        # for per-check rationale.
+        run: bash scripts/verify-sso-invariants.sh
+
       - name: Unit Tests
         run: npm run test
 

.github/workflows/cleanup-abandoned-org-top-ups.yml

@@ -0,0 +1,43 @@
+name: Cleanup Abandoned Org Top-Ups
+
+on:
+  schedule:
+    # Run daily at 02:00 UTC. Must NOT overlap the subscription-cron
+    # at 00:00 UTC (CPU + Prisma connection contention).
+    - cron: "0 2 * * *"
+  workflow_dispatch: # Allow manual triggering
+
+jobs:
+  cleanup-abandoned-org-top-ups:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    env:
+      # Database connection (required for Prisma)
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      DIRECT_URL: ${{ secrets.DIRECT_URL }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npx prisma generate
+
+      - name: Run abandoned org top-up cleanup
+        run: npx tsx jobs/cleanup/cleanup-abandoned-org-top-ups.ts
+
+      - name: Notify on failure
+        if: failure()
+        run: |
+          echo "Abandoned org top-up cleanup failed"
+          # TODO: wire to #ops-alerts Slack channel.

.github/workflows/cleanup-old-stream-recordings.yml

@@ -0,0 +1,29 @@
+name: Cleanup Old Stream Recordings
+
+on:
+  schedule:
+    # 03:00 UTC daily. Staggered after abandoned-top-ups (02:00) and
+    # reconcile-ledgers (02:30) to avoid Prisma pool contention.
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+
+jobs:
+  cleanup-old-stream-recordings:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    env:
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      DIRECT_URL: ${{ secrets.DIRECT_URL }}
+
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          cache: "npm"
+      - run: npm ci
+      - run: npx prisma generate
+      - run: npx tsx jobs/cleanup/cleanup-old-stream-recordings.ts
+      - if: failure()
+        run: echo "Stream retention sweep failed"

.github/workflows/cleanup-stale-invitations.yml

@@ -0,0 +1,47 @@
+name: Cleanup Stale Invitations
+
+on:
+  schedule:
+    # Daily at 08:00 IST (02:30 UTC). Offset from
+    # cleanup-abandoned-org-top-ups (07:30 IST / 02:00 UTC) and the
+    # subscription cron (05:30 IST / 00:00 UTC) to keep Prisma
+    # connections + CPU from contending during the cron window.
+    # GitHub Actions `schedule` interprets the cron expression in UTC.
+    - cron: "30 2 * * *"
+  workflow_dispatch: # allow manual trigger from the Actions tab
+
+jobs:
+  cleanup-stale-invitations:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    env:
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      DIRECT_URL: ${{ secrets.DIRECT_URL }}
+      UPSTASH_REDIS_REST_URL: ${{ secrets.UPSTASH_REDIS_REST_URL }}
+      UPSTASH_REDIS_REST_TOKEN: ${{ secrets.UPSTASH_REDIS_REST_TOKEN }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npx prisma generate
+
+      - name: Run stale invitation cleanup
+        run: npx tsx jobs/cleanup/cleanup-stale-invitations.ts
+
+      - name: Notify on failure
+        if: failure()
+        run: |
+          echo "Stale invitation cleanup failed"
+          # TODO: wire to #ops-alerts Slack channel.

.github/workflows/consolidated-invoice-rollup.yml

@@ -0,0 +1,49 @@
+name: Consolidated Invoice Rollup
+
+on:
+  schedule:
+    # 09:30 IST (04:00 UTC) on the 1st of every month. Only runs
+    # monthly because rolling up the same ISSUED invoices twice would
+    # create duplicate parent invoices (the cron is a one-shot per
+    # cycle). GitHub Actions `schedule` interprets cron in UTC.
+    - cron: "0 4 1 * *"
+  workflow_dispatch: # allow manual trigger for mid-cycle onboarding
+
+jobs:
+  consolidated-invoice-rollup:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    env:
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      DIRECT_URL: ${{ secrets.DIRECT_URL }}
+      UPSTASH_REDIS_REST_URL: ${{ secrets.UPSTASH_REDIS_REST_URL }}
+      UPSTASH_REDIS_REST_TOKEN: ${{ secrets.UPSTASH_REDIS_REST_TOKEN }}
+      # The cron is a no-op when this flag is unset / "false". GH Actions
+      # secrets store the live value per-environment (prod / staging).
+      ENABLE_CONSOLIDATED_INVOICE: ${{ secrets.ENABLE_CONSOLIDATED_INVOICE }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npx prisma generate
+
+      - name: Run consolidated invoice rollup
+        run: npx tsx jobs/cleanup/consolidated-invoice-rollup.ts
+
+      - name: Notify on failure
+        if: failure()
+        run: |
+          echo "Consolidated invoice rollup failed"
+          # TODO: wire to #ops-alerts Slack channel.

.github/workflows/databreach-deadline-alerts.yml

@@ -0,0 +1,49 @@
+name: DPDP DataBreach 72h Deadline Alerts
+
+on:
+  schedule:
+    # Hourly at :15 — the 72-hour DPDP reporting deadline is sharp;
+    # daily would risk crossing the cutoff between runs. The :15 slot
+    # is free across the existing cron grid.
+    - cron: "15 * * * *"
+  workflow_dispatch:
+
+jobs:
+  databreach-deadline-alerts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    env:
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      DIRECT_URL: ${{ secrets.DIRECT_URL }}
+      # Email dispatch is opt-in. When DATABREACH_ALERT_EMAIL or
+      # RESEND_API_KEY are absent the cron falls back to structured-log
+      # only (event: "dpdp.databreach.deadline").
+      DATABREACH_ALERT_EMAIL: ${{ secrets.DATABREACH_ALERT_EMAIL }}
+      RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
+      NEXT_PUBLIC_APP_URL: ${{ secrets.NEXT_PUBLIC_APP_URL }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npx prisma generate
+
+      - name: Run DataBreach deadline alerts
+        run: npx tsx jobs/compliance/databreach-deadline-alerts.ts
+
+      - name: Notify on failure
+        if: failure()
+        run: |
+          echo "DataBreach deadline alerts cron failed"
+          # TODO: wire to #ops-alerts Slack channel.

.github/workflows/dispatch-outbound-webhooks.yml

@@ -0,0 +1,43 @@
+name: Dispatch Outbound Webhooks
+
+on:
+  schedule:
+    # Every minute. The worker is idempotent — a tick that overlaps an
+    # in-flight tick observes IN_FLIGHT rows and skips them.
+    - cron: "* * * * *"
+  workflow_dispatch: # Allow manual triggering for debugging
+
+jobs:
+  dispatch-outbound-webhooks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    env:
+      # Database connection (required for Prisma)
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      DIRECT_URL: ${{ secrets.DIRECT_URL }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npx prisma generate
+
+      - name: Run outbound webhook dispatch tick
+        run: npx tsx jobs/cleanup/dispatch-outbound-webhooks.ts
+
+      - name: Notify on failure
+        if: failure()
+        run: |
+          echo "Outbound webhook dispatch tick failed"
+          # TODO: wire to #ops-alerts Slack channel.

.github/workflows/expire-contracts.yml

@@ -0,0 +1,42 @@
+name: Expire Contracts
+
+on:
+  schedule:
+    # 03:00 UTC = 08:30 IST. Quiet slot — no other crons fire here
+    # (avoids the 00:00 / 01:00 / 02:00 contention zones).
+    - cron: "0 3 * * *"
+  workflow_dispatch: # Allow manual triggering
+
+jobs:
+  expire-contracts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    env:
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      DIRECT_URL: ${{ secrets.DIRECT_URL }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npx prisma generate
+
+      - name: Run contract-expiry job
+        run: npx tsx jobs/contracts/expire-contracts.ts
+
+      - name: Notify on failure
+        if: failure()
+        run: |
+          echo "Contract-expiry cron failed"
+          # TODO: wire to #ops-alerts Slack channel.

.github/workflows/irp-uploader.yml

@@ -0,0 +1,56 @@
+name: IRP IRN Uploader
+
+on:
+  schedule:
+    # 02:30 UTC = 08:00 IST. Picked to sit between expire-contracts (03:00)
+    # and cleanup-abandoned-org-top-ups (02:00) without colliding. Daily
+    # cadence matches the CBIC 30-day retroactive IRN window.
+    - cron: "30 2 * * *"
+  workflow_dispatch: # Allow manual triggering
+
+jobs:
+  irp-uploader:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    # Gated on the ENABLE_IRP_UPLOADER repo variable (see
+    # lib/feature-flags.ts). On scheduled runs the job exits without
+    # work when the variable is unset, so we don't burn CI minutes on a
+    # stubbed connector. Manual workflow_dispatch still runs so an
+    # operator can validate the pipeline before flipping the flag on.
+    if: ${{ vars.ENABLE_IRP_UPLOADER == 'true' || github.event_name == 'workflow_dispatch' }}
+
+    env:
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      DIRECT_URL: ${{ secrets.DIRECT_URL }}
+      # ClearTax GSP credentials. When absent the underlying connector
+      # returns { status: "FAILED", reason: "STUB" } and the uploader
+      # treats that as a normal retry — the cron does not crash.
+      CLEARTAX_API_KEY: ${{ secrets.CLEARTAX_API_KEY }}
+      CLEARTAX_GSP_TOKEN: ${{ secrets.CLEARTAX_GSP_TOKEN }}
+      CLEARTAX_GSTIN: ${{ secrets.CLEARTAX_GSTIN }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npx prisma generate
+
+      - name: Run IRP uploader
+        run: npx tsx jobs/compliance/irp-uploader.ts
+
+      - name: Notify on failure
+        if: failure()
+        run: |
+          echo "IRP IRN uploader cron failed"
+          # TODO: wire to #ops-alerts Slack channel.