Merge branch 'main' into username

.gitignore

@@ -7,6 +7,8 @@ dist
 dist-ssr
 *.local
 .env
+apps/login/.env.local.?.bak
+apps/login/.env.local.??.bak
 .cache
 server/dist
 public/dist
@@ -14,4 +16,4 @@ public/dist
 packages/zitadel-server/src/app/proto
 packages/zitadel-client/src/app/proto
 
-apps/login/.vscode
+apps/login/.vscode

CONTRIBUTING.md

@@ -1,66 +1,78 @@
-# Contributing to zitadel-typescript
+# Contributing
+
+:attention: In this CONTRIBUTING.md you read about contributing to this very repository.
+If you want to develop your own login UI, please refer [to the README.md](./README.md).
 
 ## Introduction
 
-Thank you for your interest about how to contribute! As you might know there is more than code to contribute. You can find all information needed to start contributing here.
+Thank you for your interest about how to contribute!
 
-Please give us and our community the chance to get rid of security vulnerabilities by responsibly disclose this kind of issues by contacting [security@zitadel.com](mailto:security@zitadel.com).
+:attention: If you notice a possible **security vulnerability**, please don't hesitate to disclose any concern by contacting [security@zitadel.com](mailto:security@zitadel.com).
+You don't have to be perfectly sure about the nature of the vulnerability.
+We will give them a high priority and figure them out.
 
-The strongest part of a community is the possibility to share thoughts. That's why we try to react as soon as possible to your ideas, thoughts and feedback.
+We also appreciate all your other ideas, thoughts and feedback and will take care of them as soon as possible.
-We love to discuss as much as possible in an open space like in the ZITADEL [issues](https://github.com/zitadel/zitadel/issues) and [discussions](https://github.com/zitadel/zitadel/discussions) section or in our [chat](https://zitadel.com/chat), but we understand your doubts and provide further contact options [here](https://zitadel.com/contact).
+We love to discuss in an open space using [GitHub issues](https://github.com/zitadel/typescript/issues),
+[GitHub discussions in the core repo](https://github.com/zitadel/zitadel/discussions)
+or in our [chat on Discord](https://zitadel.com/chat).
+For private discussions,
+you have [more contact options on our Website](https://zitadel.com/contact).
 
-If you want to give an answer or be part of discussions please be kind. Treat others like you want to be treated. Read more about our code of conduct [here](CODE_OF_CONDUCT.md).
+## Pull Requests
 
-## How to contribute
+Please consider the following guidelines when creating a pull request.
 
-Anyone can be a contributor. Either you found a typo, or you have an awesome feature request you could implement, we encourage you to create a Pull Request.
+- The latest changes are always in `main`, so please make your pull request against that branch.
-
+- pull requests should be raised for any change
-### Pull Requests
+- Pull requests need approval of a ZITADEL core engineer @zitadel/engineers before merging
-
-- The latest changes are always in `main`, so please make your Pull Request against that branch.
-- Pull Requests should be raised for any change
-- Pull Requests need approval of a ZITADEL core engineer @zitadel/engineers before merging
 - We use ESLint/Prettier for linting/formatting, so please run `pnpm lint:fix` before committing to make resolving conflicts easier (VSCode users, check out [this ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [this Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) to fix lint and formatting issues in development)
-- We encourage you to test your changes, and if you have the opportunity, please make those tests part of the Pull Request
+- If you add new functionality, please provide the corresponding documentation as well and make it part of the pull request
-- If you add new functionality, please provide the corresponding documentation as well and make it part of the Pull Request
+
+## Setting Up The ZITADEL API
+
+If you want to have a one-liner to get you up and running,
+or if you want to develop against a ZITADEL API with the latest features,
+or even add changes to ZITADEL itself at the same time,
+you should develop against your local ZITADEL process.
+However, it might be easier to develop against your ZITADEL Cloud instance
+if you don't have docker installed
+or have limited resources on your local machine.
+
+### Developing Against Your Local ZITADEL Instance
+
+```sh
+# To have your service user key and environment file written with the correct ownership, export your current users ID.
+export ZITADEL_DEV_UID="$(id -u)"
+
+# Pull images
+docker compose --file ./acceptance/docker-compose.yaml pull
+
+# Run ZITADEL and configure ./apps/login/.env.local
+docker compose --file ./acceptance/docker-compose.yaml run setup
+```
+
+### Developing Against Your ZITADEL Cloud Instance
+
+Create the file ./apps/login/.env.local with the following content:
+```sh
+ZITADEL_API_URL=<your cloud instance URL here>
+ZITADEL_ORG_ID=<your service accounts organization id here>
+ZITADEL_SERVICE_USER_TOKEN=<your service account personal access token here>
+```
 
 ### Setting up local environment
 
-A quick guide on how to setup your ZITADEL app locally to work on it and test out any changes:
-
-1. Clone the repo:
-
-```sh
-git clone https://github.com/zitadel/zitadel-typescript.git
-cd zitadel-typescript
-```
-
-3. Install packages. Developing requires Node.js v16:
-
 ```sh
+# Install dependencies. Developing requires Node.js v16
 pnpm install
-```
 
-4. Populate `.env.local`:
+# Generate gRPC stubs
-
-Copy `/apps/login/.env` to `/apps/login/.env.local`, and add your instance env variables for each entry.
-
-```sh
-cp apps/login/.env apps/login/.env.local
-```
-
-5. Generate GRPC stub for the application:
-
-```sh
 pnpm generate
-```
 
-6. Start the developer application/server:
+# Start a local development server
-
-```sh
 pnpm dev
 ```
 
-The application will be available on `http://localhost:3000`
+The application is now available at `http://localhost:3000`
 
 That's it! 🎉

README.md

@@ -1,20 +1,30 @@
 # ZITADEL typescript with Turborepo and Changesets
 
-This is an monorepo containing all typescript/javascript packages and applications for ZITADEL. Versioning and package publishing is handled by [Changesets](https://github.com/changesets/changesets) and fully automated with GitHub Actions.
+This repository contains all TypeScript and JavaScript packages and applications you need to create your own ZITADEL Login UI.
+The repo makes use of the [build system Turbo](https://turbo.build/repo) and the [Changesets CLI for versioning the packages](https://github.com/changesets/changesets).
 
 **⚠️ This repo and packages are in alpha state and subject to change ⚠️**
 
 The scope of functionality of this repo and packages is limited and under active development.
 Once the package structure is set and all APIs are fully implemented we'll move this repo to beta state.
-You can read the [contribution guide](/CONTRIBUTING.md) on how to contribute. Questions can be raised in our [Discord Channel](https://discord.gg/erh5Brh7jE) or as an issue in this repo.
+You can read the [contribution guide](/CONTRIBUTING.md) on how to contribute.
+Questions can be raised in our [Discord channel](https://discord.gg/erh5Brh7jE) or as a [GitHub issue](https://github.com/zitadel/typescript/issues).
 
-## What's inside?
+## Developing Your Own ZITADEL Login UI
 
-This Turborepo includes the following:
+We think the easiest path of getting up and running, is the following:
 
-### Apps and Packages
+1. Fork and clone this repository
+1. [Run the ZITADEL Cloud login UI locally](#run-login-ui)
+1. Make changes to the code and see the effects live on your local machine
+1. Study the rest of this README.md and get familiar and comfortable with how everything works.
+1. Decide on a way of how you want to build and run your login UI.
+   You can reuse ZITADEL Clouds way.
+   But if you need more freedom, you can also import the packages you need into your self built application.
 
-- `login`: The new login UI powered by Next.js
+## Included Apps And Packages
+
+- `login`: The login UI used by ZITADEL Cloud, powered by Next.js
 - `@zitadel/server`: core components for establishing node client connection, grpc stub
 - `@zitadel/client`: core components for establishing web client connection, grpc stub
 - `@zitadel/react`: shared React utilities and components built with tailwindcss
@@ -24,15 +34,13 @@ This Turborepo includes the following:
 
 Each package and app is 100% [TypeScript](https://www.typescriptlang.org/).
 
-### Utilities
+## Tooling
-
-This repo has some additional tools:
 
 - [TypeScript](https://www.typescriptlang.org/) for static type checking
 - [ESLint](https://eslint.org/) for code linting
 - [Prettier](https://prettier.io) for code formatting
 
-### Useful commands
+## Useful Commands
 
 - `pnpm generate` - Build proto stubs for server and client package
 - `pnpm build` - Build all packages and the login app
@@ -41,17 +49,18 @@ This repo has some additional tools:
 - `pnpm changeset` - Generate a changeset
 - `pnpm clean` - Clean up all `node_modules` and `dist` folders (runs each package's clean script)
 
-## Versioning and Publishing packages
+## Versioning And Publishing Packages
 
-Package publishing has been configured using [Changesets](https://github.com/changesets/changesets). Here is their [documentation](https://github.com/changesets/changesets#documentation) for more information about the workflow.
+Package publishing has been configured using [Changesets](https://github.com/changesets/changesets).
+Here is their [documentation](https://github.com/changesets/changesets#documentation) for more information about the workflow.
 
 The [GitHub Action](https://github.com/changesets/action) needs an `NPM_TOKEN` and `GITHUB_TOKEN` in the repository settings. The [Changesets bot](https://github.com/apps/changeset-bot) should also be installed on the GitHub repository.
 
 Read the [changesets documentation](https://github.com/changesets/changesets/blob/main/docs/automating-changesets.md) for more information about this automation
 
-### npm
+### NPM
 
-If you want to publish package to the public npm registry and make them publicly available, this is already setup.
+If you want to publish a package to the public npm registry and make them publicly available, this is already setup.
 
 To publish packages to a private npm organization scope, **remove** the following from each of the `package.json`'s
 
@@ -63,13 +72,7 @@ To publish packages to a private npm organization scope, **remove** the followin
 
 ### GitHub Package Registry
 
-See [Working with the npm registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#publishing-a-package-using-publishconfig-in-the-packagejson-file)
+See [working with the npm registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#publishing-a-package-using-publishconfig-in-the-packagejson-file)
-
-### TODOs
-
-- Buf setup to get grpc stub in the core package
-- Decide whether a seperate client package is required to expose public client convenience methods only or generate a grpc-web output there
-- Fix #/\* path in login application
 
 ### Run Login UI
 

acceptance/Dockerfile

@@ -0,0 +1,6 @@
+FROM golang:1.19-alpine
+RUN apk add curl jq
+RUN go install github.com/zitadel/zitadel-tools@v0.4.0
+COPY setup.sh /setup.sh
+RUN chmod +x /setup.sh
+ENTRYPOINT [ "/setup.sh" ]

acceptance/docker-compose.yaml

@@ -0,0 +1,49 @@
+version: '3.8'
+
+services:
+  zitadel:
+    user: '${ZITADEL_DEV_UID}'
+    image: '${ZITADEL_IMAGE:-ghcr.io/zitadel/zitadel:latest}'
+    command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled --config /zitadel.yaml --steps /zitadel.yaml'
+    ports:
+    - "8080:8080"
+    volumes:
+      - ./machinekey:/machinekey
+      - ./zitadel.yaml:/zitadel.yaml
+    depends_on:
+      db:
+        condition: 'service_healthy'
+
+  db:
+    image: 'cockroachdb/cockroach:v22.2.2'
+    command: 'start-single-node --insecure --http-addr :9090'
+    healthcheck:
+      test: ['CMD', 'curl', '-f', 'http://localhost:9090/health?ready=1']
+      interval: '10s'
+      timeout: '30s'
+      retries: 5
+      start_period: '20s'
+    ports:
+      - "26257:26257"
+      - "9090:9090"
+
+  wait_for_zitadel:
+    image: curlimages/curl:8.00.1
+    command: [ "/bin/sh", "-c", "i=0; while ! curl http://zitadel:8080/debug/ready && [ $$i -lt 30 ]; do sleep 1; i=$$((i+1)); done; [ $$i -eq 30 ] && exit 1 || exit 0" ]
+    depends_on:
+      - zitadel
+
+  setup:
+    user: '${ZITADEL_DEV_UID}'
+    container_name: setup
+    build: .
+    environment:
+      KEY: /key/zitadel-admin-sa.json
+      SERVICE: http://zitadel:8080
+      WRITE_ENVIRONMENT_FILE: /apps/login/.env.local
+    volumes:
+    - "./machinekey:/key"
+    - "../apps/login:/apps/login"
+    depends_on:
+      wait_for_zitadel:
+        condition: 'service_completed_successfully'

acceptance/machinekey/.gitignore

@@ -0,0 +1 @@
+zitadel-admin-sa.json

acceptance/setup.sh

@@ -0,0 +1,72 @@
+#!/bin/sh
+
+set -e
+
+KEY=${KEY:-./machinekey/zitadel-admin-sa.json}
+echo "Using key path ${KEY} to the instance admin service account."
+
+AUDIENCE=${AUDIENCE:-http://localhost:8080}
+echo "Using audience ${AUDIENCE} for which the key is used."
+
+SERVICE=${SERVICE:-$AUDIENCE}
+echo "Using the service ${SERVICE} to connect to ZITADEL. For example in docker compose this can differ from the audience."
+
+WRITE_ENVIRONMENT_FILE=${WRITE_ENVIRONMENT_FILE:-$(dirname "$0")/../apps/login/.env.local}
+echo "Writing environment file to ${WRITE_ENVIRONMENT_FILE} when done."
+
+AUDIENCE_HOST="$(echo $AUDIENCE | cut -d/ -f3)"
+echo "Deferred the Host header ${AUDIENCE_HOST} which will be sent in requests that ZITADEL then maps to a virtual instance"
+
+JWT=$(zitadel-tools key2jwt --key ${KEY} --audience ${AUDIENCE})
+echo "Created JWT from Admin service account key ${JWT}"
+
+TOKEN_RESPONSE=$(curl -s --request POST \
+  --url ${SERVICE}/oauth/v2/token \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --header "Host: ${AUDIENCE_HOST}" \
+  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
+  --data scope='openid profile email urn:zitadel:iam:org:project:id:zitadel:aud' \
+  --data assertion="${JWT}")
+echo "Got response from token endpoint:"
+echo "${TOKEN_RESPONSE}" | jq
+
+TOKEN=$(echo -n ${TOKEN_RESPONSE} | jq -r '.access_token')
+echo "Extracted access token ${TOKEN}"
+
+ORG_RESPONSE=$(curl -s --request GET \
+  --url ${SERVICE}/admin/v1/orgs/default \
+  --header 'Accept: application/json' \
+  --header "Authorization: Bearer ${TOKEN}" \
+  --header "Host: ${AUDIENCE_HOST}")
+echo "Got default org response:"
+echo "${ORG_RESPONSE}" | jq
+
+ORG_ID=$(echo -n ${ORG_RESPONSE} | jq -r '.org.id')
+echo "Extracted default org id ${ORG_ID}"
+
+ENVIRONMENT_BACKUP_FILE=${WRITE_ENVIRONMENT_FILE}
+# If the original file already exists, rename it
+if [[ -e ${WRITE_ENVIRONMENT_FILE} ]]; then
+    if grep -q 'localhost' ${WRITE_ENVIRONMENT_FILE}; then
+      echo "Current environment file ${WRITE_ENVIRONMENT_FILE} contains localhost. Overwriting:"
+      cat ${WRITE_ENVIRONMENT_FILE}
+    else
+      i=0
+      # If a backup file already exists, increment counter until a free filename is found
+      while [[ -e ${ENVIRONMENT_BACKUP_FILE}.${i}.bak ]]; do
+          let "i++"
+          if [[ ${i} -eq 50 ]]; then
+              echo "Warning: Too many backup files (limit is 50), overwriting ${ENVIRONMENT_BACKUP_FILE}.${i}.bak"
+              break
+          fi
+      done
+      mv ${WRITE_ENVIRONMENT_FILE} ${ENVIRONMENT_BACKUP_FILE}.${i}.bak
+      echo "Renamed existing environment file to ${ENVIRONMENT_BACKUP_FILE}.${i}.bak"
+    fi
+fi
+
+echo "ZITADEL_API_URL=${AUDIENCE}
+ZITADEL_ORG_ID=${ORG_ID}
+ZITADEL_SERVICE_USER_TOKEN=${TOKEN}" > ${WRITE_ENVIRONMENT_FILE}
+echo "Wrote environment file ${WRITE_ENVIRONMENT_FILE}"
+cat ${WRITE_ENVIRONMENT_FILE}

acceptance/zitadel.yaml

@@ -0,0 +1,18 @@
+FirstInstance:
+  MachineKeyPath: /machinekey/zitadel-admin-sa.json
+  Org:
+    Machine:
+      Machine:
+        Username: zitadel-admin-sa
+        Name: Admin
+      MachineKey:
+        Type: 1
+
+Database:
+  Cockroach:
+    Host: db
+
+Logstore:
+  Access:
+    Stdout:
+      Enabled: true