Skip to content

Commit 46161c0

Browse files
lgutterlgutter
authored
Merge branch 'temporalio:main' into add-ca-cert-support-in-auth
2 parents 79a9167 + 0dfadd7 commit 46161c0

545 files changed

Lines changed: 32681 additions & 16137 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/auth-testing/SKILL.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
name: auth-testing
3+
description: Test OAuth2 token refresh and session expiry locally. Use when working on auth, tokens, SSO, OIDC, or session management features.
4+
---
5+
6+
# Auth Testing Skill
7+
8+
Test OAuth2 authentication flows locally using the built-in OIDC server.
9+
10+
## Quick Start
11+
12+
```bash
13+
pnpm dev:with-auth
14+
```
15+
16+
This starts:
17+
18+
- **Vite dev server**: http://localhost:3000
19+
- **UI Server** (Go): http://localhost:8081
20+
- **OIDC Server**: http://localhost:8889
21+
- **Temporal Server**: http://localhost:7233
22+
23+
## Configuration Files
24+
25+
| File | Purpose |
26+
| ------------------------------------------------ | ------------------------------------------------------- |
27+
| `server/config/with-auth.yaml` | UI server auth settings (maxSessionDuration, providers) |
28+
| `utilities/oidc-server/support/configuration.ts` | OIDC server TTLs (token expiry, session duration) |
29+
30+
## Testing Scenarios
31+
32+
### 1. Token Refresh
33+
34+
Test that tokens refresh automatically before expiry.
35+
36+
**Config**: AccessToken TTL (60s) < maxSessionDuration (2m)
37+
38+
**Steps**:
39+
40+
1. Login at http://localhost:3000
41+
2. Open browser DevTools > Network tab
42+
3. Wait ~60 seconds
43+
4. Observe `/auth/refresh` request that renews tokens
44+
45+
### 2. Session Expiry
46+
47+
Test that sessions expire and force re-login.
48+
49+
**Config**: maxSessionDuration = Session TTL (both 2m)
50+
51+
**Steps**:
52+
53+
1. Login at http://localhost:3000
54+
2. Wait 2 minutes
55+
3. Make any API request (navigate, refresh)
56+
4. Should redirect to OIDC login page
57+
58+
### 3. Unlimited Session
59+
60+
Test long-lived sessions with only token refresh.
61+
62+
**Config changes**:
63+
64+
```yaml
65+
# server/config/with-auth.yaml
66+
auth:
67+
maxSessionDuration: 0 # Disable session limit
68+
```
69+
70+
```typescript
71+
// utilities/oidc-server/support/configuration.ts
72+
ttl: {
73+
Session: 60 * 60 * 24, // 1 day
74+
}
75+
```
76+
77+
## Max Session Duration
78+
79+
The `maxSessionDuration` config enforces a hard limit on how long a user can stay logged in, independent of token expiry.
80+
81+
### How it works
82+
83+
1. **On login**: Server sets `session_start` cookie with current timestamp
84+
2. **On each request**: Server validates session age against `maxSessionDuration`
85+
3. **On expiry**: Server returns 401, UI redirects to SSO login
86+
87+
### Config location
88+
89+
```yaml
90+
# server/config/with-auth.yaml
91+
auth:
92+
enabled: true
93+
maxSessionDuration: 2m # Duration string (e.g., 30m, 1h, 24h)
94+
# Set to 0 or omit to disable
95+
```
96+
97+
### Difference from token expiry
98+
99+
| Mechanism | Controls | Behavior on expiry |
100+
| ------------------ | ------------------------ | ---------------------------------- |
101+
| Token TTL | How often tokens refresh | Silent refresh via `/auth/refresh` |
102+
| maxSessionDuration | Total session lifetime | Full re-authentication required |
103+
104+
### Use cases
105+
106+
- **Security compliance**: Force re-auth every N hours regardless of activity
107+
- **Testing**: Set short duration (2m) to quickly test session expiry flow
108+
- **Production**: Set longer duration (8h, 24h) based on security requirements
109+
110+
## Key Relationships
111+
112+
```
113+
AccessToken TTL < maxSessionDuration → Enables token refresh
114+
Session TTL = maxSessionDuration → Forces re-auth at OIDC on expiry
115+
RefreshToken TTL > Session TTL → Allows refresh within session
116+
```
117+
118+
## Current Default Values
119+
120+
| Setting | Value | Location |
121+
| -------------------- | ----- | ---------------- |
122+
| Access Token TTL | 60s | OIDC config |
123+
| ID Token TTL | 60s | OIDC config |
124+
| Refresh Token TTL | 1 day | OIDC config |
125+
| OIDC Session TTL | 2m | OIDC config |
126+
| Max Session Duration | 2m | UI server config |
127+
128+
## Debugging
129+
130+
### View auth logs
131+
132+
The Go server logs token validation:
133+
134+
```
135+
[Auth] Setting refresh token cookie (length: X)
136+
[JWT Validation] Token valid, expires at X (time remaining: X)
137+
```
138+
139+
### Check cookies
140+
141+
In browser DevTools > Application > Cookies:
142+
143+
- `user0`, `user1`... - Base64 encoded user data (short-lived)
144+
- `refresh` - HttpOnly refresh token (long-lived)
145+
- `session_start` - Session start timestamp (HttpOnly)
146+
147+
### Test endpoints
148+
149+
```bash
150+
# Get OIDC discovery
151+
curl http://localhost:8889/.well-known/openid-configuration
152+
153+
# Manual token refresh (requires valid refresh cookie)
154+
curl -X GET http://localhost:8081/auth/refresh --cookie "refresh=<token>"
155+
```
156+
157+
## Related Files
158+
159+
- `server/server/route/auth.go` - Auth routes and callbacks
160+
- `server/server/auth/auth.go` - Token validation and session management
161+
- `server/server/config/config.go` - Auth config struct
162+
- `src/lib/utilities/auth-refresh.ts` - Client-side refresh logic

‎.claude/skills/install-local-ui-in-cloud.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# Install Local UI Package in Cloud UI
2+
3+
**Trigger phrases:** "install local ui in cloud", "build ui for cloud", "test ui changes in cloud", "local ui package"
4+
5+
## Purpose
6+
7+
This skill replicates the GitHub Actions "Generate temporalio/ui PR" workflow locally when GitHub Actions is unavailable or for faster iteration. It builds the UI package from the current branch and installs it in a local cloud-ui repository.
8+
9+
## Prerequisites Check
10+
11+
Before proceeding, verify the user has cloud-ui available:
12+
13+
1. Ask: "Do you have the cloud-ui repository cloned locally?"
14+
2. If YES: Ask for the path, then instruct: "Please run `/add-dir <path-to-cloud-ui>` so I can access both repositories"
15+
3. If NO: Explain they need to clone it first, then add it with `/add-dir`
16+
17+
**CRITICAL:** Do not proceed until cloud-ui is added to the context with `/add-dir`.
18+
19+
## Workflow Steps
20+
21+
### Step 1: Build the UI Package
22+
23+
In the **ui** repository (current repo):
24+
25+
```bash
26+
# Ensure dependencies are installed
27+
pnpm install
28+
29+
# Sync SvelteKit (required before packaging)
30+
pnpm svelte-kit sync
31+
32+
# Build the library package (NOT pnpm build!)
33+
pnpm package
34+
35+
# Create the tarball
36+
pnpm pack
37+
```
38+
39+
**CRITICAL:** You must run `pnpm package` (not `pnpm build`).
40+
41+
- `pnpm package` = builds the library for distribution (creates optimized dist/)
42+
- `pnpm build` = builds the dev/docs server (wrong for this use case)
43+
44+
**Expected output:** A `.tgz` file in the ui root directory (e.g., `temporalio-ui-2.45.2.tgz`, ~1.0MB)
45+
46+
### Step 2: Install in Cloud UI
47+
48+
In the **cloud-ui** repository (must be added with `/add-dir`):
49+
50+
```bash
51+
# Navigate to cloud-ui directory
52+
cd <path-to-cloud-ui>
53+
54+
# Install the local UI package
55+
pnpm install <path-to-ui-repo>/temporalio-ui-<version>.tgz
56+
```
57+
58+
**What this does:**
59+
60+
- Updates `cloud-ui/package.json` dependencies to point `@temporalio/ui` to the local tarball
61+
- Installs the built UI package from your branch
62+
- Allows testing UI changes in the cloud environment
63+
64+
### Step 2.5: Update pnpm.overrides (CRITICAL!)
65+
66+
**IMPORTANT:** cloud-ui uses `pnpm.overrides` which takes precedence over dependencies. You MUST update this:
67+
68+
1. **Find the overrides section** in `cloud-ui/package.json` (typically near the end):
69+
70+
```json
71+
"overrides": {
72+
"@temporalio/ui": "file:./packs/temporalio-ui-XXXXXXXX.tgz",
73+
"devalue": "5.6.2"
74+
}
75+
```
76+
77+
2. **Update the override** to point to your local tarball:
78+
79+
```json
80+
"overrides": {
81+
"@temporalio/ui": "file:<absolute-path-to-ui-repo>/temporalio-ui-<version>.tgz",
82+
"devalue": "5.6.2"
83+
}
84+
```
85+
86+
3. **Run pnpm install** again to apply the override:
87+
```bash
88+
pnpm install
89+
```
90+
91+
**Why this matters:** Without updating the override, pnpm will ignore your dependency change and continue using the old pack referenced in overrides.
92+
93+
### Step 3: Start Cloud UI Dev Server
94+
95+
```bash
96+
# In cloud-ui directory
97+
pnpm dev
98+
99+
# Or for production build
100+
pnpm build
101+
```
102+
103+
Now you can test the UI changes in the cloud environment at `http://localhost:5173` (or configured port).
104+
105+
## Verification
106+
107+
After installation, verify:
108+
109+
1. Check `cloud-ui/package.json` dependencies show the local path:
110+
111+
```json
112+
"@temporalio/ui": "file:/absolute/path/to/ui/temporalio-ui-2.45.2.tgz"
113+
```
114+
115+
2. Check `cloud-ui/package.json` overrides also point to the local path:
116+
117+
```json
118+
"overrides": {
119+
"@temporalio/ui": "file:/absolute/path/to/ui/temporalio-ui-2.45.2.tgz"
120+
}
121+
```
122+
123+
3. Check `cloud-ui/node_modules/@temporalio/ui/package.json` version matches
124+
125+
4. Start dev server and verify UI changes appear
126+
127+
## Cleanup
128+
129+
To revert to the published package:
130+
131+
```bash
132+
# In cloud-ui directory
133+
pnpm install @temporalio/ui@latest
134+
```
135+
136+
## Troubleshooting
137+
138+
**"Cannot find module":**
139+
140+
- Ensure you ran `pnpm pack` in the ui repo first
141+
- Verify the tarball path is correct
142+
143+
**"Changes not appearing":**
144+
145+
- Clear cloud-ui's dev server cache and restart
146+
- Check that `pnpm pack` built the latest changes
147+
- Verify `node_modules/@temporalio/ui` contains your changes
148+
149+
**"Workspace dependency issues":**
150+
151+
- Ensure both repos use compatible pnpm/node versions
152+
- Try `pnpm install --force` in cloud-ui
153+
154+
## Example Full Workflow
155+
156+
```bash
157+
# In ui repo - build the package
158+
cd ~/code/ui
159+
git checkout my-feature-branch
160+
pnpm install
161+
pnpm svelte-kit sync
162+
pnpm package # Build the library (NOT pnpm build!)
163+
pnpm pack # Creates temporalio-ui-2.45.2.tgz (~1.0MB)
164+
165+
# In cloud-ui repo - install local package
166+
cd ~/code/cloud-ui
167+
pnpm install ~/code/ui/temporalio-ui-2.45.2.tgz
168+
169+
# CRITICAL: Update the pnpm.overrides in package.json
170+
# Edit package.json and change the overrides section:
171+
# "@temporalio/ui": "file:/Users/ross/code/ui/temporalio-ui-2.45.2.tgz"
172+
173+
# Apply the override
174+
pnpm install
175+
176+
# Start dev server
177+
pnpm dev
178+
# Visit http://localhost:3000 to test (cloud-ui uses port 3000, not 5173)
179+
```
180+
181+
## When to Use This Skill
182+
183+
- GitHub Actions is degraded/unavailable
184+
- Faster iteration than waiting for CI
185+
- Testing UI changes in cloud environment locally
186+
- Debugging integration issues between ui and cloud-ui
187+
188+
## What This Replaces
189+
190+
This replicates the `Generate temporalio/ui PR` GitHub Actions workflow which:
191+
192+
1. Checks out the UI branch
193+
2. Builds the package
194+
3. Creates a cloud-ui PR with the updated package reference
195+
196+
The local version gives immediate feedback without waiting for CI.
197+
198+
## ⚠️ CRITICAL: Do NOT Commit cloud-ui Changes
199+
200+
**IMPORTANT:** The changes made to `cloud-ui/package.json` and `cloud-ui/pnpm-lock.yaml` are for **local testing only**.
201+
202+
**DO NOT:**
203+
204+
- ❌ Commit changes in cloud-ui
205+
- ❌ Push changes in cloud-ui
206+
- ❌ Create PRs with these changes
207+
208+
**Only commit and push changes in the UI repo!**
209+
210+
The GitHub Actions workflow will create the proper cloud-ui PR automatically when it's available.

0 commit comments

Comments
 (0)