Skip to content

Commit 0907193

Browse files
rcholicrcholic
authored
Merge pull request #18 from PredicateSystems/receive_rust_sidecar
receive sidecar from rust repo
2 parents ca4094d + ef54ad7 commit 0907193

File tree

12 files changed

+893
-138
lines changed

12 files changed

+893
-138
lines changed

‎.github/workflows/update-sidecar-version.yml‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
name: Update Sidecar Version Reference
2+
3+
on:
4+
repository_dispatch:
5+
types: [sidecar-release]
6+
workflow_dispatch:
7+
inputs:
8+
version:
9+
description: 'Sidecar version tag (e.g., v0.1.0)'
10+
required: true
11+
type: string
12+
publish_sidecar_package:
13+
description: 'Publish predicate-authority-sidecar to PyPI'
14+
required: false
15+
type: boolean
16+
default: false
17+
18+
jobs:
19+
update-and-publish:
20+
name: Update sidecar version and optionally publish
21+
runs-on: ubuntu-latest
22+
permissions:
23+
contents: write
24+
id-token: write
25+
26+
steps:
27+
- uses: actions/checkout@v4
28+
29+
- name: Get version
30+
id: version
31+
run: |
32+
if [ "${{ github.event_name }}" = "repository_dispatch" ]; then
33+
VERSION="${{ github.event.client_payload.version }}"
34+
else
35+
VERSION="${{ inputs.version }}"
36+
fi
37+
# Remove 'v' prefix for Python package version
38+
PY_VERSION="${VERSION#v}"
39+
echo "version=$VERSION" >> $GITHUB_OUTPUT
40+
echo "py_version=$PY_VERSION" >> $GITHUB_OUTPUT
41+
echo "Sidecar version: $VERSION (Python: $PY_VERSION)"
42+
43+
- name: Set up Python
44+
uses: actions/setup-python@v5
45+
with:
46+
python-version: '3.11'
47+
48+
- name: Install build tools
49+
run: pip install build twine
50+
51+
- name: Update sidecar package version
52+
run: |
53+
PY_VERSION="${{ steps.version.outputs.py_version }}"
54+
sed -i "s/version = \".*\"/version = \"$PY_VERSION\"/" predicate_authority_sidecar/pyproject.toml
55+
echo "Updated predicate-authority-sidecar to version $PY_VERSION"
56+
cat predicate_authority_sidecar/pyproject.toml
57+
58+
- name: Build sidecar package
59+
working-directory: predicate_authority_sidecar
60+
run: python -m build
61+
62+
- name: Publish to PyPI (if requested or on dispatch)
63+
if: github.event_name == 'repository_dispatch' || inputs.publish_sidecar_package
64+
working-directory: predicate_authority_sidecar
65+
env:
66+
TWINE_USERNAME: __token__
67+
TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
68+
run: |
69+
echo "Publishing predicate-authority-sidecar to PyPI..."
70+
twine upload dist/* --skip-existing
71+
72+
- name: Commit version update
73+
run: |
74+
git config user.name "github-actions[bot]"
75+
git config user.email "github-actions[bot]@users.noreply.github.com"
76+
git add predicate_authority_sidecar/pyproject.toml
77+
git commit -m "chore: update sidecar package to ${{ steps.version.outputs.version }}" || echo "No changes to commit"
78+
git push
79+
80+
- name: Create notification issue
81+
uses: actions/github-script@v7
82+
with:
83+
script: |
84+
const version = '${{ steps.version.outputs.version }}';
85+
const pyVersion = '${{ steps.version.outputs.py_version }}';
86+
const releaseUrl = '${{ github.event.client_payload.release_url || 'N/A' }}';
87+
const published = '${{ github.event_name }}' === 'repository_dispatch' || '${{ inputs.publish_sidecar_package }}' === 'true';
88+
89+
await github.rest.issues.create({
90+
owner: context.repo.owner,
91+
repo: context.repo.repo,
92+
title: `Sidecar ${version} released`,
93+
body: `A new version of the Predicate Authority sidecar has been released.\n\n` +
94+
`**Sidecar Version:** ${version}\n` +
95+
`**Release:** ${releaseUrl}\n\n` +
96+
`**Python Package:** predicate-authority-sidecar ${pyVersion}\n` +
97+
`**Published to PyPI:** ${published ? 'Yes' : 'No'}\n\n` +
98+
`## Installation\n\n` +
99+
`\`\`\`bash\n` +
100+
`pip install predicate-authority[sidecar]\n` +
101+
`\`\`\`\n\n` +
102+
`Or download manually:\n` +
103+
`\`\`\`bash\n` +
104+
`predicate-download-sidecar --version ${version}\n` +
105+
`\`\`\``,
106+
labels: ['sidecar-release', 'automated']
107+
});

‎README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,19 @@ This SDK requires the **Predicate Authority Sidecar** daemon to be running. The
6666

6767
### Quick Sidecar Setup
6868

69+
**Option A: Install with sidecar (recommended)**
70+
71+
```bash
72+
# Install SDK with automatic sidecar download
73+
pip install predicate-authority[sidecar]
74+
75+
# The sidecar binary is downloaded automatically on first use
76+
# Or manually trigger download:
77+
predicate-download-sidecar
78+
```
79+
80+
**Option B: Manual download**
81+
6982
```bash
7083
# Download the latest release for your platform
7184
# Linux x64, macOS x64/ARM64, Windows x64 available
@@ -78,10 +91,30 @@ chmod +x predicate-authorityd
7891
./predicate-authorityd run --port 8787 --mode local_only --policy-file policy.json
7992
```
8093

94+
### Running the sidecar from Python
95+
96+
```python
97+
from predicate_authority import run_sidecar, is_sidecar_available, download_sidecar
98+
99+
# Download if not available
100+
if not is_sidecar_available():
101+
download_sidecar()
102+
103+
# Run sidecar as subprocess
104+
process = run_sidecar(port=8787, policy_file="policy.json")
105+
106+
# Later: graceful shutdown
107+
process.terminate()
108+
process.wait()
109+
```
110+
81111
## Installation
82112

83113
```bash
84114
pip install predicate-authority
115+
116+
# Or with sidecar binary:
117+
pip install predicate-authority[sidecar]
85118
```
86119

87120
For local editable development in this monorepo, install both package roots

‎docs/authorityd-operations.md‎

Lines changed: 91 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,67 @@
22

33
This guide shows how to run the local sidecar daemon, provide a policy file, and verify health/status endpoints.
44

5+
---
6+
7+
## Sidecar Installation
8+
9+
The sidecar (`predicate-authorityd`) is a lightweight Rust binary that handles policy evaluation and mandate signing.
10+
11+
### Option A: Install via pip (recommended for Python users)
12+
13+
```bash
14+
# Install SDK with sidecar extra - downloads binary automatically
15+
pip install predicate-authority[sidecar]
16+
17+
# Or manually trigger download after installing core SDK
18+
pip install predicate-authority
19+
predicate-download-sidecar
20+
```
21+
22+
Binary location after install:
23+
- macOS: `~/Library/Application Support/predicate-authority/bin/predicate-authorityd`
24+
- Linux: `~/.local/share/predicate-authority/bin/predicate-authorityd`
25+
- Windows: `%LOCALAPPDATA%/predicate-authority/bin/predicate-authorityd.exe`
26+
27+
### Option B: Download binary directly
28+
29+
Download pre-built binaries from [GitHub Releases](https://github.com/PredicateSystems/predicate-authority-sidecar/releases):
30+
31+
| Platform | Binary |
32+
|----------|--------|
33+
| macOS ARM64 (Apple Silicon) | `predicate-authorityd-darwin-arm64.tar.gz` |
34+
| macOS x64 (Intel) | `predicate-authorityd-darwin-x64.tar.gz` |
35+
| Linux x64 | `predicate-authorityd-linux-x64.tar.gz` |
36+
| Linux ARM64 | `predicate-authorityd-linux-arm64.tar.gz` |
37+
| Windows x64 | `predicate-authorityd-windows-x64.zip` |
38+
39+
```bash
40+
# Example: macOS ARM64
41+
curl -LO https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-darwin-arm64.tar.gz
42+
tar -xzf predicate-authorityd-darwin-arm64.tar.gz
43+
chmod +x predicate-authorityd
44+
./predicate-authorityd --version
45+
```
46+
47+
### Option C: Use from Python code
48+
49+
```python
50+
from predicate_authority import run_sidecar, is_sidecar_available, download_sidecar
51+
52+
# Download if needed
53+
if not is_sidecar_available():
54+
download_sidecar()
55+
56+
# Start as subprocess
57+
process = run_sidecar(port=8787, policy_file="policy.json")
58+
59+
# Graceful shutdown
60+
process.terminate()
61+
process.wait()
62+
```
63+
64+
---
65+
566
## 1) Sample `policy.json`
667

768
Create `examples/authorityd/policy.json`:
@@ -31,87 +92,68 @@ Create `examples/authorityd/policy.json`:
3192

3293
## 2) Start the daemon
3394

34-
Run from repo root:
95+
### Basic local mode
3596

3697
```bash
37-
PYTHONPATH=. predicate-authorityd \
98+
./predicate-authorityd run \
3899
--host 127.0.0.1 \
39100
--port 8787 \
40101
--mode local_only \
41-
--policy-file examples/authorityd/policy.json \
42-
--policy-poll-interval-s 2.0 \
43-
--credential-store-file ./.predicate-authorityd/credentials.json
102+
--policy-file policy.json
44103
```
45104

46-
By design, mandate/revocation cache is in-memory (ephemeral) unless you explicitly
47-
enable persistence with `--mandate-store-file`.
48-
49-
### Optional: enable persisted mandate/revocation cache (parity extension)
50-
51-
Use this only when restart-recovery for local revocations/mandate lineage is required.
52-
If omitted, default behavior remains ephemeral.
105+
### With local identity registry
53106

54107
```bash
55-
PYTHONPATH=. predicate-authorityd \
108+
./predicate-authorityd run \
56109
--host 127.0.0.1 \
57110
--port 8787 \
58111
--mode local_only \
59-
--policy-file examples/authorityd/policy.json \
60-
--mandate-store-file ./.predicate-authorityd/mandates.json
112+
--policy-file policy.json \
113+
--identity-file ./local-identities.json
61114
```
62115

63-
### Optional: enable control-plane shipping
116+
### Cloud-connected mode (control-plane sync)
64117

65-
To automatically ship proof events and usage records to
66-
`predicate-authority-control-plane`, set:
118+
Connect to Predicate Authority control-plane for policy sync, revocation push, and audit forwarding:
67119

68120
```bash
69-
export CONTROL_PLANE_URL="http://127.0.0.1:8080"
70-
export CONTROL_PLANE_TENANT_ID="dev-tenant"
71-
export CONTROL_PLANE_PROJECT_ID="dev-project"
72-
export CONTROL_PLANE_API_KEY="<bearer-token>"
121+
export PREDICATE_API_KEY="your-api-key"
73122

74-
PYTHONPATH=. predicate-authorityd \
123+
./predicate-authorityd run \
75124
--host 127.0.0.1 \
76125
--port 8787 \
77-
--mode local_only \
78-
--policy-file examples/authorityd/policy.json \
79-
--control-plane-enabled \
80-
--control-plane-fail-open
126+
--mode cloud_connected \
127+
--policy-file policy.json \
128+
--control-plane-url https://api.predicatesystems.dev \
129+
--tenant-id your-tenant \
130+
--project-id your-project \
131+
--predicate-api-key $PREDICATE_API_KEY \
132+
--sync-enabled
81133
```
82134

83-
### Optional: enable long-poll policy/revocation sync from control-plane
135+
### Local IdP mode (development/air-gapped)
84136

85-
Use this when running `cloud_connected` mode and you want active policy/revocation
86-
updates pushed through long-poll sync instead of waiting for file-based policy polling.
137+
For development or air-gapped environments without external IdP:
87138

88139
```bash
89-
export CONTROL_PLANE_URL="http://127.0.0.1:8080"
90-
export CONTROL_PLANE_TENANT_ID="dev-tenant"
91-
export CONTROL_PLANE_PROJECT_ID="dev-project"
92-
export CONTROL_PLANE_API_KEY="<bearer-token>"
140+
export LOCAL_IDP_SIGNING_KEY="replace-with-strong-secret"
93141

94-
PYTHONPATH=. predicate-authorityd \
142+
./predicate-authorityd run \
95143
--host 127.0.0.1 \
96144
--port 8787 \
97-
--mode cloud_connected \
98-
--policy-file examples/authorityd/policy.json \
99-
--control-plane-enabled \
100-
--control-plane-sync-enabled \
101-
--control-plane-sync-project-id "$CONTROL_PLANE_PROJECT_ID" \
102-
--control-plane-sync-environment "prod" \
103-
--control-plane-sync-wait-timeout-s 15 \
104-
--control-plane-sync-poll-interval-ms 200
145+
--mode local_only \
146+
--policy-file policy.json \
147+
--identity-mode local-idp \
148+
--local-idp-issuer "http://localhost/predicate-local-idp" \
149+
--local-idp-audience "api://predicate-authority"
105150
```
106151

107-
Quick checks:
152+
Quick health checks:
108153

109154
```bash
110-
# daemon sync health counters
111-
curl -s http://127.0.0.1:8787/status | jq '.control_plane_sync_poll_count, .control_plane_sync_update_count, .control_plane_sync_error_count, .control_plane_last_sync_error'
112-
113-
# daemon metrics includes control-plane sync counters
114-
curl -s http://127.0.0.1:8787/metrics | rg "predicate_authority_control_plane_sync_total"
155+
curl -s http://127.0.0.1:8787/health | jq
156+
curl -s http://127.0.0.1:8787/status | jq
115157
```
116158

117159
### Signing key safety note (required until mandate `v2` claims)

0 commit comments

Comments
 (0)